Project: M3 (Observability and Analysis / Observability)
File: DOCUMENTATION.md

M3 is a large and complex project, and any help you can offer to explain it better is most welcome. If you have a suggestion for the documentation M3 welcomes it, and documentation pull requests follow the same process as . The rest of this document explains how to setup the documentation locally and the structure of the content. The M3 documentation uses , a static site generator written in Go. . If you also want to run and serve the M3 documentation, you need the custom theme, . Clone or download it into the same directory as the M3 codebase. To run some tests and test the production build steps (this doesn't run M3 itself), you need . Hugo hosts the M3 documentation, website, and Open API spec. The website is the HTML, CSS, and JavaScript files in the site/static folder. Edit those files to make any changes. Hugo hosts the Open API spec from the site/static/openapi folder. To make changes to the spec, edit the spec.yml file in src/query/generated/assets, and a CI job generates the file that Hugo hosts automatically. The site/config folder has configuration for Hugo, split into three folders: A default config.toml file in site/config/\default_ Overridden configuration for development and production environments in site/config/development and site/config/production respectively. The site/layouts folder adds a several changes and overridden files to the Victor theme used by the M3 documentation. The site/content folder contains the documentation files, organized by folders that match the paths for URLs. The includes folder is a special folder not served as part of the documentation and files used by other files. The M3 documentation uses its own (open source) theme, Victor. You can read all the features that theme provides in . Victor is a theme based on Hugo modules, about how to use and update it. The M3 documentation adds the following extra shortcodes: `{{% apiendpoint %}}` - Combines the values of `Params.api.localCordinator` + `Params.api.apiEndpoint` as defined in the site configuration to output the base API endpoint for M3 running on a localhost. `{{% docker-version %}}` - Outputs the value of `Params.releases.docker` as defined in the site configuration to output the consistent current Docker release. `{{% now %}}` - Outputs the current Unix timestamp to allow for up to date timestamps in code

As noted in the prerequisites section, if you want to run the documentation locally to see how your edits look with `hugo server`, you need to have the Victor theme in the same parent directory as the M3 codebase, as `hugo server` runs in Hugo's "development" mode (and matches site/config/development/config.toml). This does mean that as you make changes to the theme or documentation, it refreshes automatically in the browser preview. Sometimes Hugo doesn't refresh included files, so you may need to restart the server process. The M3 documentation has a number of tests that need to pass before a pull request is merged to master and deployed. These include: Link checking with htmltest To run them you need Docker installed and running, and at the top level of the M3 project, run `make clean install-vendor-m3 docs-test`. If the test is successful you see green text, if not, htmltest tells you which links in which pages you need to fix. There are a couple of different ways to build the documentation depending what you want to do. If you want to build only the most up-to-date version of the docs, you can use `hugo` to build. If you want to build all versions of the docs using Hugo run in Docker (this is what CI does to test the documentation). From the top level of the project, run `make docs-build`. If you want to build all versions of the docs with a system-installed version of Hugo (this is what Netlify does to build and serve the documentation). From the top level of the project, run `make site-build`. M3 releases versions with some slight changes to documentation for each one which users can access from the drop down menu under the right hand navigation. Archiving a version of the documentation is a slightly complex process as Hugo doesn't natively support versioning. Add the new version and path to site/config/production/config.toml in the format: ```toml [[params.versions]] version = "{versionNumber}" url = "/v{versionNumber}/docs" ``` Add the `/v{versionNumber}` path before each `{{ .RelPermalink}}` in the two anchor tags in site/layouts/partials/navbar.html Make sure the Victor theme is at least version 0.2.11 Create and tag the commits with the name "docs/v{versionNumber}" Switch to a new branch that will add the new version to the master branch Add the new version to site/config/production/config.toml Also add the new version to site/config/production/config.toml in every pre-existing docs version tag Switch back to the branch from step 5 Test everything locally with `make site-build` Push the new tag to the remote repository