Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# Documenting
TeraFlowSDN's documentation runs on [MkDocs](https://www.mkdocs.org/).
## Eligibility
Documenting TeraFlowSDN 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 does it work?
There are 2 ways to upgrade documentation published on the [TFS Documentation] website:
* Push any change on **develop** branch will force update of the **develop** version on the [TFS Documentation] website;
* Create a tag, this will create a version with the tag name on the [TFS 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 [TFS 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:
- Home : ./index.md
- Deployment Guide: ./deployment_guide.md
- Development Guide: ./development_guide.md
- Run Experiments: ./run_experiments.md
- Feature and bugs: ./features_and_bugs.md
- Supported SBIs and Network Elements: ./supported_sbis_and_network_elements.md
- Supported NBIs: ./supported_nbis.md
[...]
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
```
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 TeraFlowSDN and should reference the version (useful shortcut is ``{{{ documentation_version }}}``).
## Getting Started
To contribute to TeraFlowSDN's documentation, you need to follow these easy steps:
1) Clone the [Documentation repository](https://labs.etsi.org/rep/tfs/documentation) with:
```bash
git clone https://labs.etsi.org/rep/tfs/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 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
python -m pip install -r requirements.txt
```
4) Wait for all downloads to finish and start the local ``mkdocs`` server:
```bash
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](https://labs.etsi.org/rep/tfs/documentation/-/issues) 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);
4. Check if errors are not being produced by ``mkdocs`` [locally](#getting-started);
5. Commit and push changes to the new branch;
6. Create a MR 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 **TeraFlowSDN** code repository is ready for a new release, we need to follow these steps (made by a **TSC Member**):
1. Create a MR from **develop** towards **main**;
2. When **develop** is merged to **main**... then **create a tag with the released version** scheme... and you're done!
[TFS Web]: https://tfs.etsi.org/ "TFS Web"
[TFS Documentation]: https://tfs.etsi.org/documentation/ "TFS Documentation"