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 does it work?

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: stable timeline on which tags are made;
- develop: edge timeline, also 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.

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 OpenCAPIF and should reference the version (useful shortcut is `{{{ documentation_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 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 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 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 OpenCAPIF code repository is ready for a new release, we need to follow these steps (made by a TSC Member):

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