Documentation

Overview

The documentation:

Is based on the HUGO framework written in Go. The underlaying language is markdown plus the extensions provided by hugo.
The framwork including the theme used is maintained in the following repo.
The hugo version, currently at 0.129.0 must match the image version defined in the root makefile and the framework repo, defined in .drone.yml.
- Building the theme is part of the loaded framework while building the documentation is done using a separate container.
- Any intended upgrade of the hugo version implies a check if the theme builds correctly and must be applied to all doc sourcing repos. On errors, stick on the current hugo version or update the theme accordingly!
The documentation sources are distributed over several repos such as ocis, web and others. When building, these sources act individually and only those sources are build and pushed to the web that come from the respective repo. The definition what is going where is defined in the framework repo. This means, each merge of a docs change in one of the sourcing repos only pushes that change to the site. There is no global build process and inter doc links must be treated therefore very carefully !
The documentation setup is, with only a few exceptions, identical for both the ocis and the web repo. This means, for example, running commands locally are the same, the documentation process section below applies for both; only drone uses some specifics.
Any files or folders that need to be excluded from the build process must be defined in the referenced framework repository above, in the file config.yaml.

Documentation Process

When building the ocis documentation, the process differes slightly when building locally or when merging. Though both processes generate they docs, the end up in different locations.

General
Beside building docs, some additional files/folders will be copied required for the process, see the makefile for details.
Locally
The rendered build stays in the branch that is currently active and is NOT part of a git change, though additional changed files show up and may need to be committed. The build can be viewed normally, for details see below.
Merge
When a docs PR gets merged, the content of the docs/ folder gets “copied”. For master the target is the docs branch or a respective docs-stable- branch otherwise. The latter must be configured on new stable versions. The docs branch is the source of truth for the developer documentation.

Building the Documentation

For building the documentation locally, you need to have make, docker and go installed.
See the oCIS README for more details and minimum versions required.

Regulary, at least once after cloning, branching or rebasing, run make generate to update the assets. This ensures that all data that is accessed by the docs build process is up-to-date.

Run the make commands from the oCIS root, the makefile contains all required targets.
Use make help for more details.

For any changes, you must fully build the documentation first to preview it.
For ease of working, open two terminals and change to the oCIS root. The terminals are numberd as (1) and (2).
- At first start, from any terminal, run sudo make docs-clean to have a clean build environment.
  sudo is required for deletion, because files generated by hugo, which runs in a container, are created by root.
- Do all the doc changes required in the docs repository.
- Run (1) make docs-local. This will run all steps locally as drone would do but without branch copying or pushing to the web. When omitting this step and just serving content, the documentation might build locally but may fail when creating a PR.
- Run (2) make docs-serve to serve the documentation. You can now view the built result in the browser.
- On any more changes made, run (1) make docs-copy. The changes will be built on the fly via the running docs-serve command.
To preview the documentation locally without changing content, run the following commands in order.
This builds the documentation without artifacts and makes it available on localhost:1313.
- sudo make docs-clean
- make docs-local
- make docs-serve

Remarks

Note that you may get files changed reported like env_vars.yaml by just running the make docs commands. You can discard any of these as they come from an internal helper process step necessary. To take care on those changed files, see the Environment Variables documentation.

Please keep this documentation in sync with the oCIS source code of the master branch.

Changes on the documentation are automatically applied to this site when merged to the master branch.