Generate the documentation¶

This website is generated by rs-documentation with MkDocs and the Material for MkDocs theme, from:

the system-level pages of rs-documentation, in its docs/ folder,
the Markdown documentation of the other RS-PYTHON repositories (their README.md and docs/ folders), cloned under docs/<repository>,
the Python API documentation, generated from the docstrings with mkdocstrings.

It is generated and published by the Generate documentation GitHub workflow of rs-documentation, on each push. For each repository, the workflow uses the branch with the same name as the rs-documentation branch if it exists, else the develop branch. Only the develop branch is published, at https://home.rs-python.eu/rs-documentation/; for the other branches the website is built to check that it is valid.

How it works¶

File	Role
`.github/scripts/repositories.txt`	The repositories cloned under `docs/`.
`mkdocs.yml.tpl`	Template of the MkDocs configuration: theme, extensions, navigation menu...
`.github/scripts/generate_mkdocs.sh`	Generates the Python API documentation pages (with `build_pydoc.sh`) and the `mkdocs.yml` file from the template.
`hooks/rspy_links.py`	MkDocs hook that turns the absolute GitHub links to the Markdown pages of the RS-PYTHON repositories into links inside the website, see Writing guidelines.
`hooks/rspy_boilerplate.py`	MkDocs hook that removes the boilerplate repeated in all the repositories: the "Contributing" and "Licensing" sections of the README of each repository, and the license header at the start of the code examples.
`includes/abbreviations.md`	Definitions of the acronyms, displayed as tooltips on every page.
`.github/scripts/render_diagrams.sh`	Renders the PlantUML diagrams, see Diagrams.

Only the Markdown pages and the images of the repositories are published, not their source code (see the exclude_docs setting of mkdocs.yml.tpl).

Generate the website locally¶

Prerequisites: Python 3.13 and Poetry 2.x.

Clone rs-documentation:

git clone https://github.com/RS-PYTHON/rs-documentation.git
cd rs-documentation

Make the other repositories available under docs/, either by cloning them:

cd docs
for repo in $(cat ../.github/scripts/repositories.txt); do
  git clone -b develop https://github.com/RS-PYTHON/${repo}.git
done
cd ..

or, if you already have them in your workspace, with symbolic links:

cd docs
for repo in $(cat ../.github/scripts/repositories.txt); do
  ln -s /path/to/your/workspace/${repo} ${repo}
done
cd ..

Install the dependencies. The Python API documentation is generated by static analysis of the source code of the repositories cloned under docs/, so they don't need to be installed:
```
poetry install
```
Generate the Python API documentation and the mkdocs.yml file:
```
./.github/scripts/generate_mkdocs.sh
```
Build the website in the site/ folder, or serve it on http://127.0.0.1:8000 with live reload:
```
poetry run mkdocs build
poetry run mkdocs serve
```

Check the warnings displayed by MkDocs: they report the broken links and anchors.

Writing guidelines¶

Where to write: document each component in its own repository, starting from its README.md file. Write the documentation that concerns the system as a whole (several repositories) in rs-documentation. Avoid duplicating information: link to the page that describes it instead.
README files follow the same structure in all the repositories: title, short description and its role in RS-Python, overview, getting started, documentation links, related repositories, contributing and licensing. All of them end with the same licensing footer:
```
## Licensing

The code in this project is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).

---

![](https://raw.githubusercontent.com/RS-PYTHON/.github/refs/heads/main/profile/banner_logo.jpg)

This project is funded by the EU and ESA.
```
These "Contributing" and "Licensing" sections are displayed on GitHub, but the rspy_boilerplate hook removes them from this website, so they are not repeated on every page.
Links inside a repository are relative, e.g. [Catalog](users/catalog.md#search), so they work both on GitHub and in this website.
Links to another repository use the absolute GitHub URL of the page on the develop branch, e.g. https://github.com/RS-PYTHON/rs-server/blob/develop/docs/doc/users/catalog.md, so they work on GitHub. The rspy_links hook turns them into links inside this website, and MkDocs checks them. The pages of rs-documentation itself are linked with https://github.com/RS-PYTHON/rs-documentation/blob/develop/docs/<page>.md.
URLs of the platform: use the URLs of the reference platform (*.ops.rs-python.eu) in the examples, and remind the reader to replace the domain name by the one of their platform.
No links to private resources: the issue tracker and the wiki of the project are not public, don't link to them. Don't describe the non-public repositories.
Current state only: describe the system as it is, not its history. The changes are listed in the release notes.
Link to the public documentation of the standards and of the open-source components that we use, and to the Copernicus, CDSE and Destination Earth websites.

Diagrams¶

Diagrams are written as text, so they can be reviewed and updated easily:

Mermaid diagrams, for simple flowcharts and sequence diagrams, directly in the Markdown pages in a ```mermaid code block. They are rendered by GitHub and by this website.
PlantUML diagrams, for more complex diagrams (use cases, components, deployment, classes...). Each repository keeps their sources in docs/uml/<name>.plantuml, and the rendered images in docs/images/<name>.svg. The @startuml name must match the file name. After modifying a diagram, render the SVG images (requires Docker) and commit them:
```
# From the rs-documentation folder, for the repositories given as arguments
.github/scripts/render_diagrams.sh . ../rs-server ../rs-client-libraries
```

The PlantUML source is embedded in each SVG image, so a diagram can also be reopened from its image, e.g. with the PlantUML online server.

The illustrations that need logos and a free layout, such as the main components of the System architecture, are written directly as SVG images in docs/images, without PlantUML source. Their logos come from Simple Icons (CC0 license).

Screenshots are saved as PNG images.