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:

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.