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 be equal on both the ocis repo (cat .bingo/Variables.mk | grep HUGO) and in the framework repo (defined in .drone.yml).

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 very carefully !

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 you need to have make 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.

To view the documentation locally or after fixing typos only, without adding new content such as links or new documents, just run make -C docs docs-serve from within the root level of the oCIS git repository. This will make the documentation available on localhost:1313 and also do a hot reload if you change something in the (non autogenerated) documentation files.
When doing more changes than fixing typos, you need to fully build the documentation running make docs-drone-test. 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. Use the command described above to serve docs for a browser preview.

Note that you may get files changed reported like env_vars.yaml by just running the make command. 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.