https://github.com/weaveworks/weave-gitops
Archived. Profiles work has moved toProfiles website
This website is built using Docusaurus 2, a modern static website generator.
Contents
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.
userdocs
From 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>