Skip to content

Documenting

TeraFlowSDN's documentation runs on MkDocs.

Eligibility

Documenting TeraFlowSDN 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.

How does it work?

There are 2 ways to upgrade documentation published on the TFS Documentation website:

  • Push any change on develop branch will force update of the develop version on the TFS Documentation website;
  • Create a tag, this will create a version with the tag name on the TFS Documentation website.

Branches

This documentation repository has 2 protected branches:

  • main: stable timeline on which tags are made;
  • develop: edge timeline, also published on the TFS Documentation website.

Structure

In the mkdocs.yml file you will find the navigation structure of the documentation, there you can sections with sub-sections.

For example:

nav:
  - Home : ./index.md
  - Deployment Guide: ./deployment_guide.md
  - Development Guide: ./development_guide.md
  - Run Experiments: ./run_experiments.md
  - Feature and bugs: ./features_and_bugs.md
  - Supported SBIs and Network Elements: ./supported_sbis_and_network_elements.md
  - Supported NBIs: ./supported_nbis.md
[...]

Please take a moment to understand the current structure of the documentations and think to update after contributing if necessary.

Main Page

The page shown first is at doc/index.md. That page should be updated with the latest changes of TeraFlowSDN and should reference the version (useful shortcut is {{{ documentation_version }}}).

Getting Started

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

1) Clone the Documentation repository with:

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

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

cd ./documentation
git checkout develop

3) Setup a virtual environment:

  • On Linux/macOS:
python3 -m venv venv # Linux/macOS
source venv/bin/activate #Linux/macOS
  • On Windows:
python -m venv venv # Windows
venv\Scripts\activate # Windows

4) Setup a local mkdocs server by installing requirements:

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.

Release a New Version of the Documentation

When TeraFlowSDN code repository is ready for a new release, we need to follow these steps (made by a TSC Member):

  1. Create a MR from develop towards main;
  2. When develop is merged to main... then create a tag with the released version scheme... and you're done!