Skip to content

# Documenting

OpenSlice's documentation runs on MkDocs.

## Eligibility

Documenting OpenSlice is limited to active contributors. So, if you:

1. are an active member or participant;
2. wish to contribute to it;
3. you're ready!

## System and Structure

MkDocs is a fast and simple static site generator that's geared towards building project documentation. Documentation source files are written in `Markdown`, and configured with a single `YAML` configuration file. Start by reading the introductory tutorial, then check the User Guide for more information.

## Getting Started

To contribute to OpenSlice's documentation, you need to follow these easy steps:

1) Clone the Documentation repository with:

    git clone https://labs.etsi.org/rep/osl/documentation.git

2) Checkout the develop branch (incoming contributions are only accepted to the develop branch):

    cd ./documentation
    git checkout develop

3) Setup a local `mkdocs` server with a virtual environment:

Linux + macOS Windows

    python3 -m venv venv
    source venv/bin/activate

    python -m venv venv
    venv\Scripts\activate

    python -m pip install -r requirements.txt

4) Wait for all downloads to finish and start the local `mkdocs` server:

    mkdocs serve

5) Document! 😊

> You should always make sure that the local MkDocs server terminal is not producing any `INFO`/`WARNING` messages regarding your contributions.

### Add Documentation During Development

To update the documentation properly during development, follow those additional steps:

1. Create an issue on the documentation GitLab repository;
2. Create a new branch with the develop branch as a source;
3. Update the documentation and any relevant parts (ie: the `index.md` with new functionalities for the latest version);
4. Check if errors are not being produced by `mkdocs` locally;
5. Commit and push changes to the new branch;
6. Create a MR request towards develop;
7. Send the request for review and approval to at least one TSC Member.

> The documentation website supports branches, so your accepted changes will be reflected to the develop branch which then becomes the release branch after each corresponding cycle.

## Learn more

If you wish to learn more about the documentation system, check this link.