weaveworks/profiles-userdocs

Repository containing the user documentation of Profiles.

Archived. Profiles work has moved to https://github.com/weaveworks/weave-gitops

Profiles website

This website is built using Docusaurus 2, a modern static website generator.

Contents

• Local Development
  • From project root
  • From userdocs
• Deployment
  • Automated
  • Manual
• Autogenerated docs
  • pctl command help generation
  • Schema generation

Local Development

From project root

From the root profiles directory you can simply run make local-docs. This command installs required packages, starts a local development server and opens up a browser window at localhost:3000. Most changes are reflected live without having to restart the server.

From userdocs

Ensure you are in userdocs, and run:

yarn install

followed by

yarn start

Note: if you are running this command from here any autogenerated files will not be created and you may see rendering errors, or missing or blank pages. See below for more details.

To generate static content into the build directory which can be served using any static contents hosting service, run:

yarn build

Deployment

Automated

The docs are automatically deployed as part of a Github Action, found currently at profiles/.github/workflows/deploy-docs.yaml.

They run at https://profiles.dev/.

Manual

You should not need to do this, as we automatically deploy the docs on release, but if for whatever reason you need to deploy manually, and if you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

Autogenerated docs

The following pages are generated on the fly to save us from having to update docs with every small change:

• Everything in /docs/pctl/
• /docs/author-docs/profile-definition-schema.mdx
• /docs/catalog-docs/catalog-source-schema.mdx

pctl command help generation

Both the deploy action and make local-docs will run pctl docgen to create individual pages for pctl <command> --help output at the correct location to be rendered in the docs.

The docgen command outputs a markdown file for each user-facing command.

$ pctl docgen --help
NAME:
   pctl docgen - generate the cli doc pages

USAGE:
   pctl docgen --out <relative-path-of-dir-to-write-docs>

OPTIONS:
   --path value  The relative path to write the docs out. Default: pwd.
   --help, -h    show help (default: false)

Schema generation

The JSON schemas for ProfileDefinition and ProfileCatalogSource are created using the cmd/schema package in profiles. The command will parse the given Go object, strip out any irrelevant data, and generate a schema v7 JSON file. Both the deploy action and the make local-docs will run this and ensure the files get generated in the correct location.

The schemas are then rendered to look a bit like yaml by src/components/Schema.js in the docs directory.

$ go run cmd/schema/main.go
Usage: schema <object-name> <outfile>