Our docs are written using Hugo using the Doks theme as the base.
Hugo is a static site generator. It converts markdown files to static html pages. Edit the markdown files, and view the rendered site with the Hugo server.
The development environment for Hugo requires NodeJS, with a number of
dependencies that need to be downloaded from the package.json file.
npm install
Our documentation contains an API reference section that is autogenerated from the custom resource definitions of each ACK service. These reference documents need to be re-generated each time there is a change to any of the fields or versions of any of these CRDs.
The scripts/gen_reference.py file will attempt to navigate every service
controller repository in the $GOPATH and build a full model of every custom
resource and version based off the CRD base files. It will then output these
models using jinja2 templates into markdown files under
content/reference/<service>/<version>/<resource>.md.
To run scripts/gen_reference.py navigate to community/docs, install the
python requirements.txt file and then run python3 ./scripts/gen_reference.py.
🟧 Test locally, including both the content and the navigation structure.
Note: Before you can run the local preview for the first time, you will need to generate the API reference.
The docs are just Markdown files and in order to see the rendered preview locally (before PRing the repo), do:
$ npm start
Start building sites …
hugo v0.87.0-B0C541E4+extended linux/amd64 BuildDate=2021-08-03T10:57:28Z VendorInfo=gohugoio
| EN
-------------------+------
Pages | 112
Paginator pages | 0
Non-page files | 5
Static files | 75
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Built in 877 ms
Watching for changes in /local/home/go/src/github.com/aws-controllers-k8s/community/docs/{archetypes,assets,babel.config.js,content,data,layouts,node_modules,package.json,static}
Watching for config changes in /local/home/go/src/github.com/aws-controllers-k8s/community/docs/config/_default
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop
The Hugo documentation includes
information on the structure of the docs/ folder, and writing in markdown.
To publish updated docs, commit changes to the markdown files and open a pull request. When the commit is merged, the updated documentation is published by a Prow job that runs whenever a new tag of any controller is published, or if any part of the documentation is updated.