mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2025-12-31 01:10:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

[docs-only] Update the docs helper readme and other related files

Browse Source
This commit is contained in:
mmattel
2024-03-21 13:59:42 +01:00
parent 12da64593a
commit febb391de7
4 changed files with 396 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/README.md
View File

@@ -1,3 +1,5 @@
# documentation
# Documentation
To contribute to documentation please see also: [Documentation](http://owncloud.dev/ocis/development/build-docs/)
Note that when running a helper like `make -C docs docs-generate` locally, you will see the generated output in e.g. docs/services/<service-name>. When merging a PR, the pipeline will generate the output in the master branch but finally moves it into the `docs` branch. You will therefor _not_ see changes in the docs folder of the master branch!

54
docs/helpers/README.md
View File

@@ -12,16 +12,17 @@
* [General Extended Envvars Info](#general-extended-envvars-info)
* [Extract Extended Envvars](#extract-extended-envvars)
* [Generate Extended Envvar Docs](#generate-extended-envvar-docs)
* [Tasks for New Releases](#tasks-for-new-releases)
* [Backporting](#backporting)
## Introduction
`docs/helpers` contains small go programs creating docs by extracting information from the code. The `main.go` program is manually started with `make docs-generate` or via the CI. It calls the other required programs and has these main responsibilities:
`docs/helpers` contains go programs creating docs by extracting information from the code. The `main.go` program is manually started with `make docs-generate` or via the CI. It calls the other required programs and has these main responsibilities:
- Generate docs for envvars in config structs including deprecations if there are any.
- Extract and generate docs for `extended` envvars that are not mentioned in config structs (aka "rogue" envvars).
- Extract and generate docs for `global` envvars which occur in multiple services.
- Create `docs/service/<service-name>/_index.md` from `service/<service-name>/README.md` files while keeping the existing `_index.md` if the README.md has not been created so far.
- Create `docs/service/<service-name>/_index.md` from `service/<service-name>/README.md` files while keeping the existing `_index.md` if the service README.md has not been created so far. Also see the important note at [docs README](../README.md).
## Output Generated
@@ -32,7 +33,7 @@
## Admin Doc Process
Whenever a build from the [ocis admin](https://github.com/owncloud/docs-ocis) or any other related documentation is triggered, the files generated here are included into the build process and added in a proper manner defined by the admin documentation. The updated documentation will then show up on the [web](https://doc.owncloud.com/ocis/next/).
Whenever a build from the [ocis admin](https://github.com/owncloud/docs-ocis) documentation or any other admin related documentation is triggered, files generated here in the ocis repo are included into the build process and added in a proper manner defined by the admin documentation. The updated documentation will then show up on the public [admin documentation](https://doc.owncloud.com/ocis/next/).
## Branching
@@ -76,7 +77,7 @@ Global envvars are gathered by checking if the envvar is available in more than
It can happen that extended envvars are found but do not need to be published as they are for internal use only. Those envvars can be defined to be ignored for further processing.
IMPORTANT:
**IMPORTANT:**
- First Time Identification
Once an extended envvar has been identified, it is added to the `extended_vars.yaml` file found in this folder but never changed or touched by the process anymore. There is one exception with respect to single/double quote usage. While you can (and will) manually define a text like: `"'/var/lib/ocis'"`, quotes are transformed by the process in the .yaml file to: `'''/var/lib/ocis'''`. There is no need to change this back, as the final step transforms this correctly for the adoc table.
@@ -140,20 +141,59 @@ type Variable struct {
// DependendServices []Service `yaml:"dependend_services"`
}
```
This yaml file can later be manually edited to add descriptions, default values, etc.
IMPORTANT: `RawName`, `Path` and `FoundInCode` are automatically filled by the program. DO NOT EDIT THESE VALUES MANUALLY.
**IMPORTANT**: `RawName`, `Path` and `FoundInCode` are automatically filled by the program. DO NOT EDIT THESE VALUES MANUALLY.
### Generate Extended Envvar Docs
The process further picks up the `yaml` file generated in the `Extract Rogue Envvars` step and renders it to an adoc file (a table is created) using a go template. The template file for this step can be found at `docs/templates/ADOC_extended.tmpl`.
## Tasks for New Releases
Close before a new release gets publsihed, but **before** a new ocis admin docs branch is created, some tasks need to be done manually. These tasks cant be done automatically! By processing these manual tasks, doc related and important files get updated respectively created, ready to be consumed by the admin docs. The following situations can occur, see the solution provided:
1. A new admin docs branch gets created. Building the branched admin docs report inexisting referenced delta files.\
&#8594; Run the manual tasks described below and restart building the branched admin docs.
2. A new ocis release is close to be released, the manual tasks **have not been** processed so far.\
&#8594; Run the manual tasks.
3. A new ocis release is close to be released, the manual tasks **have been** processed some time ago.\
&#8594; Re-run the manual tasks.
4. Re-running the manual tasks have been forgotten to be processed before publishing the final release.\
&#8594; Re-run the manual tasks AND backport the results into the `docs-stable-x.y` branch.
### Task List
1. From the ocis root, run `make -C docs docs-generate` and check if there is a change in the `extended-envars.yaml` output.\
&#8594; In case, process [Extended Envvars](#extended-envvars). When done, re-run the make command and check if the output of `./docs/services/_includes/adoc/extended_configvars.adoc` matches the expectations.
2. In `./docs/helpers` run: `go run . --help` This will give you an overview of available commands.
1. Run `go run . all` to generate respectively update required base files.\
&#8594; Any change in `env_vars.yaml` must be check out to be available in master.
2. Create delta files for added, removed and deprecated envvars. To do so type:\
`go run . env-var-delta-table` and use as parameter the versions you want to compare. Example: `v5.0.0 v6.0.0`.
3. List and check the files created in `./docs/helpers/output/env-deltas/`. These are the files defining a table in markdown and asciidoc where the former is used in the dev docs and the latter is consumed by the admin docs build process.\
**Important**: To make the files consumable, the following attribute must be changed in the respective admin docs branch definition: [docs-ocis/antora.yml](https://github.com/owncloud/docs-ocis/blob/master/antora.yml) `env_var_delta_name`. Only the delta filename part needs to be used. The complete filenames will be assembled automatically.
```
v5.0.0-v6.0.0 -->
v5.0.0-v6.0.0-added.md
v5.0.0-v6.0.0-deprecated.md
v5.0.0-v6.0.0-removed.md
```
3. Commit all changes, create a PR and post merging, adapt, if necessary, the ocis admin docs. With any merge in the admin docs, the newly created content for that ocis admin docs branch will be consumed.
## Backporting
The ocis repo contains branches which are necessary for the documentation. The `docs` branch is related to changes in master, necessary for owncloud.dev and the admin docs referencing master content when it comes to envvars and yaml files.
When a new stable ocis release (branch) is published, like `stable-2.0`, an additional branch (including CI) is set up manually by the dev team for referencing docs content like `docs-stable-2.0` - related to envvars and yaml files only - and added to the CI.
When a new stable ocis release (branch) is published, like `stable-5.0`, an additional branch (including CI) is set up manually by the dev team for referencing docs content like `docs-stable-5.0` - related to envvars and yaml files only - and added to the CI.
In case it is necessary to transport a change from master to a stable branch like `docs-stable-2.0`, you must backport the original changes that will create that file to the `stable-2.0` branch. The CI will then take care of creating the results in the target `docs-stable-2.0`.
In case it is necessary to transport a change from master to a stable branch like `docs-stable-5.0`, you must backport the original changes that will create that file to the `stable-5.0` branch. The CI will then take care of creating the results in the target `docs-stable-5.0`.
Cases for a backport can be a typo in an envvar description you want to have fixed in a stable branch too or a file was created after the stable branch was set up but needs to be available in that branch.

625
docs/helpers/env_vars.yaml
View File

File diff suppressed because it is too large Load Diff

44
docs/helpers/extended_vars.yaml
View File

@@ -16,9 +16,17 @@ variables:
description: ""
do_ignore: true
- rawname: MICRO_LOG_LEVEL
path: ocis-pkg/log/log.go:31
path: ocis-pkg/log/log.go:36
foundincode: true
name: MICRO_LOG_LEVEL
type: ""
default_value: ""
description: ""
do_ignore: false
- rawname: MICRO_LOG_LEVEL
path: ocis-pkg/log/log.go:31
foundincode: false
name: MICRO_LOG_LEVEL
type: string
default_value: Error
description: Set the log level for the internal go micro framework. Only change
@@ -26,12 +34,20 @@ variables:
do_ignore: false
- rawname: MICRO_LOG_LEVEL
path: ocis-pkg/log/log.go:35
foundincode: true
foundincode: false
name: MICRO_LOG_LEVEL
type: ""
default_value: ""
description: ""
do_ignore: true
- rawname: MICRO_LOG_LEVEL
path: ocis-pkg/log/log.go:32
foundincode: true
name: MICRO_LOG_LEVEL
type: ""
default_value: ""
description: ""
do_ignore: false
- rawname: _registryEnv
path: ocis-pkg/registry/registry.go:114
foundincode: true
@@ -43,6 +59,14 @@ variables:
and ''mdns'' are deprecated and will be removed in a later version. Only change
on supervision of ownCloud Support.'
do_ignore: false
- rawname: _registryAddressEnv
path: ocis-pkg/registry/registry.go:118
foundincode: true
name: MICRO_REGISTRY_ADDRESS
type: ""
default_value: ""
description: ""
do_ignore: true
- rawname: _registryAddressEnv
path: ocis-pkg/natsjsregistry/registry.go:145
foundincode: true
@@ -52,14 +76,6 @@ variables:
description: The bind address of the internal go micro framework. Only change on
supervision of ownCloud Support.
do_ignore: false
- rawname: _registryAddressEnv
path: ocis-pkg/registry/registry.go:118
foundincode: true
name: MICRO_REGISTRY_ADDRESS
type: ""
default_value: ""
description: ""
do_ignore: true
- rawname: _registryPasswordEnv
path: ocis-pkg/natsjsregistry/registry.go:163
foundincode: true
@@ -96,6 +112,14 @@ variables:
description: The default directory location for config files. See the General Info
section in the documentation for more details on defaults.
do_ignore: false
- rawname: RUN_CMD_TEST
path: internal/testenv/test.go:33
foundincode: true
name: RUN_CMD_TEST
type: ""
default_value: ""
description: ""
do_ignore: true
- rawname: parts[0]
path: ocis-pkg/config/envdecode/envdecode.go:382
foundincode: true