This respository contains the documentation of OpenCAPIF.
## How it works?
## Getting Started
There are 2 ways to upgrade documentation published on [OCF Documentation]:
* Push any change on **develop** branch will force update of **develop** version on [OCF Documentation].
* Create a tag, this will create a version with tag name on [OCF Documentation].
## Repository 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 on documentation published on [OCF Documentation]
## What should be the flow to add documentation during development
The steps to upgrade documentation are:
1. Perform the development of functionality on capif code respository.
2. Create an issue on [Documentation Gitlab](https://labs.etsi.org/rep/ocf/documentation/-/issues)
3. Create new branch with source from **develop**.
4. Update documentation:
1.***Remember to update index.md with new functionalities for latest version***
2. New testplan is defined? **Update test plan documentation**
5. Check if all new documentation is ok using **mike**[Checking documentation with local deployment](#checking-documentation-with-local-deployment) section.
6. Push changes to branch.
7. Create Merge Request.
8. Send Merge Request to one TSC Member to approve it.
## Release new version of documentation
When **OpenCAPIF** code repository is ready to share a new release we need to follow next steps by a **TSC Member**:
1. Create a new branch with 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 released version.**
## Checking documentation with local deployment
The easy way to check if documentation will be generated properly is check locally with [mike utility](https://github.com/jimporter/mike).
## Requirements
1. You will need python or any python virtual environment installed on your computer with **pip**.
2. Install mike and mkdocs-material:
```
pip install -q mkdocs-material mike
```
3. Set default tag:
```
mike set-default --allow-undefined version1
```
4. Run mike development server:
```
mike deploy version1; mike serve
```
5. Use any web browser to reach http://localhost:8000/version1/
> **To see changes on documentation you will need to restart mike server**
## What is the documentation structure
At mkdocs.yml you will have the navigation structure of documentation, there you can sections with sub-sections. after semicolon you can place the markdown to use on it. For example:
OpenCAPIF's documentation runs on [MkDocs](https://www.mkdocs.org/).
...
...
@@ -8,18 +7,58 @@ OpenCAPIF's documentation runs on [MkDocs](https://www.mkdocs.org/).
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!
## Documentation System and Structure
## 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 [OCF Documentation]:
* Push any change on **develop** branch will force update of **develop** version on the [OCF Documentation] website;
* Create a tag, this will create a version with 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.
4) Wait for all downloads to finish and start the mkdocs server:
4) Wait for all downloads to finish and start the local ``mkdocs`` server:
```bash
mkdocs serve
...
...
@@ -55,3 +94,29 @@ mkdocs serve
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](https://labs.etsi.org/rep/ocf/documentation/-/issues);
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. New test plan is defined? **Update test plan documentation**
5. Check if errors are being produced by ``mkdocs``[locally](#getting-started);
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**.
