Merge pull request #11565 from owncloud/update_docs_about_docs

[docs-only] Update docs about docs

Author: mmattel

README.md

@@ -105,7 +105,12 @@ See the [Install Infinite Scale on a Server](https://doc.owncloud.com/ocis/next/
 
 ### Use the ocis Repo as Source
 
-Use this method to run an instance with the latest code. This is only recommended for development purposes. The minimum go version required is 1.22. Note that you need, as a prerequisite, a C compile environment installed because some dependencies like reva have components that require c-go libraries/tool-chains. The command installing for debian based systems is: `sudo apt install build-essential`. To build and run a local instance with demo users:
+Use this method to build and run an instance with the latest code. This is only recommended for development purposes.
+
+The minimum go version required is `1.24`.\
+Note that you need a C compile environment installed as a prerequisite because some dependencies, like reva, have components that require C-Go libraries and toolchains. The command installing for debian based systems is: `sudo apt install build-essential`.
+
+To build and run a local instance with demo users:
 
 ```console
 # get the source

docs/ocis/build-docs.md

@@ -0,0 +1,52 @@
+---
+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 be equal on both the ocis repo (`cat .bingo/Variables.mk | grep HUGO`) and in the framework repo (defined in `.drone.yml`).\
+{{< hint info >}}
+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 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
+
+{{< hint info >}}
+* For building the documentation you need to have `make` 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.
+{{< /hint >}}
+
+* **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](http://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]({{< ref "../services/general-info/envvars/" >}}) 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]({{< ref "../" >}}) when merged to the master branch.