github.com/m3db/m3@v1.5.1-0.20231129193456-75a402aa583b/DOCUMENTATION.md (about)

     1  # Documentation Guide
     2  
     3  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](CONTRIBUTING.md).
     4  
     5  The rest of this document explains how to setup the documentation locally and the structure of the content.
     6  
     7  ## Setup Documentation Locally
     8  
     9  ### Prerequisites
    10  
    11  The M3 documentation uses [Hugo](https://gohugo.io/), a static site generator written in Go. [Find installation instructions in the Hugo documentation](https://gohugo.io/getting-started/installing/).
    12  
    13  If you also want to run and serve the M3 documentation, you need the custom theme, [Victor](https://github.com/chronosphereio/victor). Clone or download it into the same directory as the M3 codebase.
    14  
    15  To run some tests and test the production build steps (this doesn't run M3 itself), you need [Docker](https://www.docker.com).
    16  
    17  ## Folder Structure
    18  
    19  Hugo hosts the M3 documentation, website, and Open API spec.
    20  
    21  ### Website
    22  
    23  The website is the HTML, CSS, and JavaScript files in the _site/static_ folder. Edit those files to make any changes.
    24  
    25  ### Open API Docs
    26  
    27  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.
    28  
    29  ### Configuration
    30  
    31  The _site/config_ folder has configuration for Hugo, split into three folders:
    32  
    33  -   A default  _config.toml_ file in _site/config/\_default_
    34  -   Overridden configuration for development and production environments in _site/config/development_ and _site/config/production_ respectively.
    35  
    36  ### Theme Overrides
    37  
    38  The _site/layouts_ folder adds a several changes and overridden files to the Victor theme used by the M3 documentation.
    39  
    40  ### Documentation
    41  
    42  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.
    43  
    44  #### Theme
    45  
    46  The M3 documentation uses its own (open source) theme, Victor. You can read all the features that theme provides in [the repository for Victor](https://github.com/chronosphereio/victor).
    47  
    48  Victor is a theme based on Hugo modules, [read more in the Hugo docs](https://gohugo.io/hugo-modules/use-modules/) about how to use and update it.
    49  
    50  #### Shortcodes
    51  
    52  The M3 documentation adds the following extra shortcodes:
    53  
    54  -   `{{% 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.
    55  -   `{{% docker-version %}}` - Outputs the value of `Params.releases.docker` as defined in the site configuration to output the consistent current Docker release.
    56  -   `{{% now %}}` - Outputs the current Unix timestamp to allow for up to date timestamps in code examples.
    57  
    58  ## Running Documentation
    59  
    60  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_).
    61  
    62  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.
    63  
    64  ## Testing Documentation
    65  
    66  The M3 documentation has a number of tests that need to pass before a pull request is merged to master and deployed. These include:
    67  
    68  -   Link checking with htmltest
    69  
    70  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.
    71  
    72  ## Building Documentation
    73  
    74  There are a couple of different ways to build the documentation depending what you want to do.
    75  
    76  - If you want to build only the most up-to-date version of the docs, you can use `hugo` to build.
    77  - 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`.
    78  - 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`.
    79  
    80  ## Creating a New Documentation Version
    81  
    82  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.
    83  
    84  Archiving a version of the documentation is a slightly complex process as Hugo doesn't natively support versioning.
    85  
    86  1.  Add the new version and path to _site/config/production/config.toml_ in the format:
    87  
    88      ```toml
    89      [[params.versions]]
    90        version = "{versionNumber}"
    91        url = "/v{versionNumber}/docs"
    92      ```
    93  2.  Add the `/v{versionNumber}` path before each `{{ .RelPermalink}}` in the two anchor tags in _site/layouts/partials/navbar.html_
    94  3.  Make sure the Victor theme is at least version 0.2.11
    95  4.  Create and tag the commits with the name "docs/v{versionNumber}"
    96  5.  Switch to a new branch that will add the new version to the master branch
    97  6.  Add the new version to _site/config/production/config.toml_
    98  7.  Also add the new version to _site/config/production/config.toml_ in every pre-existing docs version tag
    99  8.  Switch back to the branch from step 5
   100  9.  Test everything locally with `make site-build`
   101  10. Push the new tag to the remote repository