Align documentation guidelines

[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.

[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?

### How does it work?

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

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

This documentation repository has 2 protected branches:

This documentation repository has 2 protected branches:

  * **main**: this branch will store the information stable;

  * **main**: stable timeline on which tags are made;

  * **develop**: any change uploaded on this branch will upgrade **develop** version of the documentation published on the [OCF Documentation] website.

  * **develop**: edge timeline, also published on the [OCF Documentation] website.

### Structure

### Structure

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

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

*For example:*

*For example:*

```yaml

```yaml

nav:

nav:

  - Overview:

  - Overview:

  * Contribute: details about how to contribute code and docs;

  * Contribute: details about how to contribute code and docs;

  * FAQ.

  * FAQ.

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

### Main Page

### 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.

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

## Getting Started

git checkout develop

git checkout develop

```

```

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

3) Setup a virtual environment:

* On Linux/macOS:

  ```bash

  python3 -m venv venv # Linux/macOS

  source venv/bin/activate #Linux/macOS

  ```

* On Windows:

  ```bash

  python -m venv venv # Windows

  venv\Scripts\activate # Windows

  ```

4) Setup a local ``mkdocs`` server by installing requirements:

```bash

```bash

python3 -m venv venv

python -m pip install -r requirements.txt

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:

4) Wait for all downloads to finish and start the local ``mkdocs`` server:

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*);

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](#getting-started);

4. Check if errors are not being produced by ``mkdocs`` [locally](#getting-started);

5. Commit and push changes to the new branch;

5. Commit and push changes to the new branch;

6. Create a merge/pull request;

6. Create a merge/pull request towards **develop**;

7. Send the request for review and approval to at least one **TSC Member**.

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.

> 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

### 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**):

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**;

1. Create a PR from **develop** towards **main**;

2. Create a Merge request from **develop** to **main**;

2. When **develop** is merged to **main**... then **create a tag with the released version** scheme... and you're done!

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 Web]: https://ocf.etsi.org/ "OCF Web"

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

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

mkdocs

mkdocs-material

mkdocs-glightbox

mkdocs-markdownextradata-plugin

mike

 No newline at end of file