diff --git a/doc/contribute/documenting.md b/doc/contribute/documenting.md index 6f3d2c9b00afea5a415dbfb544f7fced1b6ab68c..0ffd4e0ba2dfb05427b1f8fb2239066c63884c29 100644 --- a/doc/contribute/documenting.md +++ b/doc/contribute/documenting.md @@ -14,7 +14,7 @@ Documenting OpenCAPIF is limited to active contributors. So, if you: [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: @@ -25,14 +25,15 @@ There are 2 ways to upgrade documentation published on the [OCF Documentation] w 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. + * **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:* + ```yaml nav: - Overview: @@ -54,9 +55,11 @@ As you can see here, we have at the time of writing this page, 5 main sections: * 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, 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 @@ -75,14 +78,26 @@ cd ./documentation 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 -python3 -m venv venv -source venv/bin/activate -python -m pip install mkdocs -python -m pip install mkdocs-material -python -m pip install mike +python -m pip install -r requirements.txt ``` 4) Wait for all downloads to finish and start the local ``mkdocs`` server: @@ -104,18 +119,17 @@ To update the documentation properly during development, follow those additional 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); 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**. -> 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 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**. +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! [OCF Web]: https://ocf.etsi.org/ "OCF Web" [OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation" diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..10a0c2fe3f8d351a9e4307e156a2f6e21d2141cb --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +mkdocs +mkdocs-material +mkdocs-glightbox +mkdocs-markdownextradata-plugin +mike \ No newline at end of file