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 (and commit)! 😊

Before committing, you should make sure that the local MkDocs server terminal is not producing any INFO/WARNING messages regarding your contributions.

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.

Add Documentation During Development

To update the documentation during development, follow those steps:

  1. Perform the development of functionality on capif code repository;
  2. Create an issue on GitLab;
  3. Create a new branch with source from develop;
  4. Update documentation:
    1. Remember to update index.md with new functionalities for the latest version;
    2. If a new test plan is defined, remember to update the test plan documentation
  5. Check if errors are being produced by mkdocs locally;
  6. Push changes to branch;
  7. Create a merge/pull request;
  8. Send the request to review to at least one TSC Member for approval.

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.