Skip to content

Documenting

OpenCAPIF's documentation runs on MkDocs.

Eligibility

Documenting OpenCAPIF 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 it works?

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

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

Branches

This documentation repository has 2 protected branches:

  • main: this branch will store the information stable;
  • develop: any change uploaded on this branch will upgrade develop version of the documentation published on the OCF 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:
  - Overview:
      - Introduction: index.md
  - Getting Started:
      - How to Run: ./gettingstarted/howtorun.md
  - Testing:
      - Test Plan: ./testing/testplan/README.md
      - Robot Framework: ./testing/robotframework/README.md
      - Postman: ./testing/postman/README.md
  - FAQ: ./FAQ.md

As you can see here, we have at the time of writing this page, 5 main sections:

  • Overview: here we placed high-level information like version changelog, some initial scripts, ...;
  • Getting Started: this section contains a simple way to start working with the project;
  • Testing: detailed information of how to test OpenCAPIF, and test plan developed to ensure the code has all implemented functionality checked;
  • Contribute: details about how to contribute code and docs;
  • FAQ.

Main Page

The page shown first is at doc/index.md. That page should be updated with the latest changes of OpenCAPIF, also including the version.

Getting Started

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

1) Clone the Documentation repository with:

git clone https://labs.etsi.org/rep/ocf/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, using a virtual environment:

python3 -m venv venv
source venv/bin/activate
python -m pip install mkdocs
python -m pip install mkdocs-material
python -m pip install mike

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 or if a new test plan has been defined, remember to update the test plan documentation);
  4. Check if errors are not being produced by mkdocs locally;
  5. Commit and push changes to the new branch;
  6. Create a merge/pull request;
  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 becomes the release branch after each corresponding cycle.

Release a New Version of the Documentation

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

  1. Create a new branch with the released version, and merge it to develop;
  2. Create a Merge request from develop to main;
  3. When develop is merged to main, then we need to create a tag with the released version.