documenting.md

# Documenting

OpenCAPIF's documentation runs on [MkDocs](https://www.mkdocs.org/).

## 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](https://www.mkdocs.org/) 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](https://www.mkdocs.org/getting-started/), then check the [User Guide](https://www.mkdocs.org/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:*
```yaml
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](https://labs.etsi.org/rep/ocf/documentation) with:

```bash
git clone https://labs.etsi.org/rep/ocf/documentation.git
```

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

```bash
cd ./documentation
git checkout develop
```

3) Setup a local ``mkdocs`` server, using a virtual environment:

```bash
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:

```bash
mkdocs serve
```

5) Document (and commit - *follow the steps in the section below before committing*)! 😊

> You should always 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 properly during development, follow those steps:

1. Create an issue on the documentation [GitLab](https://labs.etsi.org/rep/ocf/documentation/-/issues) repository;
2. Create a new branch with the **develop** branch as a source;
3. Update the 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**
4. Check if errors are being produced by ``mkdocs`` [locally](#getting-started);
5. Push changes to branch;
6. Create a merge/pull request;
7. 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**.

[OCF Web]: https://ocf.etsi.org/ "OCF Web"
[OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation"