improved docs

Roche · Nov 14, 2023 · 1a943dd · 1a943dd
1 parent 730771d
commit 1a943dd
Show file tree

Hide file tree

Showing 7 changed files with 148 additions and 118 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -20,4 +20,5 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 live:
+	rm -rf "$(BUILDDIR)"
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)"
diff --git a/docs/source/api.md b/docs/source/api.md
@@ -9,42 +9,3 @@ The API is documented using the [OpenAPI](https://swagger.io/specification/) spe
 See the [installation](installation) section for details on how to run foxops.
 
 When calling the HTTP API from a Python application, consider using the [foxops-client-python](https://github.com/Roche/foxops-client-python) library!
-
-## Usage as a Python Library
-
-While foxops is mostly intended to be used via the http API, the entire functionality is also available via Python functions that can be called from your custom application.
-
-```{eval-rst}
-.. module:: foxops
-```
-
-## fengine
-
-The following interfaces are exposed from the `foxops.fengine` package:
-
-### Models
-
-```{eval-rst}
-.. autoclass:: foxops.engine.IncarnationState
-   :members:
-
-.. autofunction:: foxops.engine.load_incarnation_state
-
-.. autofunction:: foxops.engine.load_incarnation_state_from_string
-
-.. autofunction:: foxops.engine.save_incarnation_state
-```
-
-### Initialization
-
-```{eval-rst}
-.. autofunction:: foxops.engine.initialize_incarnation
-```
-
-### Update
-
-```{eval-rst}
-.. autofunction:: foxops.engine.update_incarnation
-
-.. autofunction:: foxops.engine.update_incarnation_from_git_template_repository
-```
diff --git a/docs/source/configfile_reference.md b/docs/source/configfile_reference.md
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -12,8 +12,8 @@ tutorials/index
 :maxdepth: 2
 :caption: References
 
+reference/templates
 terminology
-configfile_reference
 api
 ```
 

diff --git a/docs/source/installation.md b/docs/source/installation.md
@@ -102,6 +102,9 @@ The following is needed to run foxops:
   * `FOXOPS_HOSTER_TYPE` - Set to `gitlab` for a production deployment
   * `FOXOPS_HOSTER_GITLAB_ADDRESS` - Set to the address of your GitLab instance (e.g. `https://gitlab.com`) (if hoster type is set to `gitlab`)
   * `FOXOPS_HOSTER_GITLAB_TOKEN` - Set to a GitLab access token that has access to all repositories (incarnations & templates) that foxops should manage (if hoster type is set to `gitlab`)
+    * The Gitlab token must have the `api` scope to be able to perform all required actions (pushing/pulling repos, creating merge requests).
+    * Be aware that foxops pushes all changes using this token (and therefore, might also trigger pipelines with this token). As Gitlab pipelines inherit the permissions from the user (in this case, the token) creating a change, make sure this token has sufficient access.
+  * `FOXOPS_LOG_LEVEL` - Set to `DEBUG` to enable debug logging (optional, default is `INFO`)
 
 #### Kubernetes Example
 

diff --git a/docs/source/reference/templates.md b/docs/source/reference/templates.md
@@ -0,0 +1,142 @@
+# Templates
+
+## Directory Structure
+
+The directory structure of a template is as follows:
+
+```
+root folder (git repo root)/
+├── template/
+│   └── ... any files / folders
+└── fengine.yaml
+```
+
+## Metadata (fengine.yaml)
+The `fengine.yaml` file holds metadata that is required by fengine when rendering the template into an incarnation. Most importantly it contains definitions of template variables, but can also override some settings that affect the rendering process.
+
+An example `fengine.yaml` file looks like this:
+
+```yaml
+rendering:
+  excluded_files:
+    - vendor/**/*
+
+variables:
+  application_name:
+    type: string
+    description: Name of the application. Don't use spaces.
+  author:
+    type: string
+    description: Name of the author. Use format "Name <email>".
+  index:
+    type: string
+    description: The PyPI index
+    default: pypi.org
+```
+
+### Variable Definitions
+
+The `variables` section defines the variables that are available to the template. Each variable has a name, a type and a description.
+
+The following basic types are supported:
+
+* `string`: A string value
+* `integer`: An integer value
+* `boolean`: A boolean value
+
+It is mandatory to give a description for every variable definition. A default value can also be specified as shown in the example above.
+
+(list-variables)=
+#### List Variables
+
+A variable can also be a list of values. For now, only string types are supported. Example:
+
+```yaml
+variables:
+  authors:
+    type: list
+    element_type: string
+    
+    description: List of authors
+    
+    default:
+      - John Doe
+      - Jane Doe
+```
+
+#### Nested Object Variables
+
+Variables can be nested arbitrarily deep. Default values can not be specified on the variables of type object itself - instead specify them on the nested variables. Example:
+
+```yaml
+variables:
+  address:
+    type: object
+    description: Address of the author
+    
+    children:
+      street:
+        type: string
+        description: Street name
+      number:
+        type: integer
+        description: Street number
+      city:
+        type: string
+        description: City name
+        default: Zurich
+```
+
+## Template Variables & Engine
+
+Foxops will render all files within the `template/` folder into the incarnation - and uses the Jinja2 template engine to render the files. This means that you can use all the features of Jinja2 in your templates.
+
+Here you can find the [full documentation](https://jinja.palletsprojects.com/en/3.1.x/templates) of that template language.
+
+### Using Variables
+
+To use a variable in a file, you can use the `{{ .. }}` syntax, e.g.:
+
+```jinja
+This template was incarnated by {{ author }}.
+
+Template version that was used {{ fengine.template.version }}
+{# note: this is the syntax for accessing nested variables #}
+{# ... and this btw. is a comment which will be excluded in the rendered file #}
+```
+
+#### Conditionals
+
+To use a conditional in a file, you can use the `{% if .. %}` syntax, e.g.:
+
+```jinja
+{% if author == "foxops" %}
+This template was incarnated by foxops.
+{% else %}
+This template was incarnated by someone else.
+{% endif %}
+```
+
+#### Loops
+
+To use a loop in a file, you can use the `{% for .. %}` syntax, e.g.:
+
+```jinja
+This template was incarnated by:
+{% for author in authors %}
+* {{ author }}
+{% endfor %}
+```
+
+To use for loops, you need a [list variable](#list-variables) to get started.
+
+#### ... and much more (includes, macros, assignments, ...)
+
+Consult the [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/templates) documentation for more information.
+
+### Predefined Variables
+
+Foxops comes with a few predefined variables that you can use in every template without explicitly defining them:
+
+* `{{ fengine.template.repository}}` - The path of the template repository
+* `{{ fengine.template.repository_version }}` - The version of the template that is being used to render the incarnation
diff --git a/docs/source/tutorials/write-template-from-scratch.md b/docs/source/tutorials/write-template-from-scratch.md
@@ -62,7 +62,7 @@ variables:
         default: Jane Doe
 ```
 
-More variable types exist (like complex objects or lists): Read more about this in the [template configuration reference](../configfile_reference).
+More variable types exist (like complex objects or lists): Read more about this in the [template configuration reference](../reference/templates).
 
 ## Exclude Files from Rendering