---
title: "Documentation"
date: 2020-07-27T08:39:38+00:00
weight: 8
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/development
geekdocFilePath: build-docs.md
---

{{< toc >}}

## Overview

The documentation:

* Is based on the [HUGO](https://gohugo.io/) 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](https://github.com/owncloud/owncloud.github.io). 
* 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`.\
{{< hint info >}}
* 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!
{{< /hint >}}

* 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](https://github.com/owncloud/owncloud.github.io/blob/main/.batchfile). 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.

* {{< hint info >}}
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`. 
{{< /hint >}}

## 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

{{< hint info >}}
* For building the documentation locally, you need to have `make`, `docker` and `go` installed.\
  See the [oCIS README](https://github.com/owncloud/ocis/#use-the-ocis-repo-as-source) 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.
{{< /hint >}}

* **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](http://localhost:1313).
  * `sudo make docs-clean`
  * `make docs-local`
  * `make docs-serve`

## Remarks

{{< hint info >}}
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]({{< ref "../services/general-info/envvars/" >}}) documentation.
{{< /hint >}}

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]({{< ref "../" >}}) when merged to the master branch.
