Skip to content

Latest commit

 

History

History
101 lines (60 loc) · 5.68 KB

DOCUMENTATION.md

File metadata and controls

101 lines (60 loc) · 5.68 KB
Raw

Documentation Guide

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 code contributions.

The rest of this document explains how to setup the documentation locally and the structure of the content.

Setup Documentation Locally

Prerequisites

The M3 documentation uses Hugo, a static site generator written in Go. Find installation instructions in the Hugo documentation.

If you also want to run and serve the M3 documentation, you need the custom theme, Victor. 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 Docker.

Folder Structure

Hugo hosts the M3 documentation, website, and Open API spec.

Website

The website is the HTML, CSS, and JavaScript files in the site/static folder. Edit those files to make any changes.

Open API Docs

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.

Configuration

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.

Theme Overrides

The site/layouts folder adds a several changes and overridden files to the Victor theme used by the M3 documentation.

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.

Theme

The M3 documentation uses its own (open source) theme, Victor. You can read all the features that theme provides in the repository for Victor.

Victor is a theme based on Hugo modules, read more in the Hugo docs about how to use and update it.

Shortcodes

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 examples.

Running Documentation

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.

Testing Documentation

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.

Building Documentation

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.

Creating a New Documentation Version

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.

  1. Add the new version and path to site/config/production/config.toml in the format:

    [[params.versions]]
  version = "{versionNumber}"
  url = "/v{versionNumber}/docs"

  2. Add the /v{versionNumber} path before each {{ .RelPermalink}} in the two anchor tags in site/layouts/partials/navbar.html

  3. Make sure the Victor theme is at least version 0.2.11

  4. Create and tag the commits with the name "docs/v{versionNumber}"

  5. Switch to a new branch that will add the new version to the master branch

  6. Add the new version to site/config/production/config.toml

  7. Also add the new version to site/config/production/config.toml in every pre-existing docs version tag

  8. Switch back to the branch from step 5

  9. Test everything locally with make site-build

  10. Push the new tag to the remote repository