diff --git a/README.md b/README.md index 573def1cc63154cbcfb764b1013dc73ed4cf6543..6c78b1fab8bb4987f0b5525a2c0d86ca3aec4c48 100644 --- a/README.md +++ b/README.md @@ -2,97 +2,6 @@ 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: -``` -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 we have 4 main sections: -* Overview: - * Here we must place high level information like, version changelog, some inital scripts, ... -* Getting Started: - * This section must contain a simple way to start working with project. -* Testing: - * Detailed information of **how to test** OpenCAPIF, and test plan developed to ensure the code has all implemented functionallity checked. -* FAQ - -## Main page - -The page shown on first view is at **doc/index.md** - -That page should be updated with latest changes on CAPIF, also including the version. - - -[OCF Web]: https://ocf.etsi.org/ "OCF Web" -[OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation" \ No newline at end of file +The full process on how to contribute to this documentation is available [here](doc/contribute/documenting.md). \ No newline at end of file diff --git a/doc/contribute/documenting.md b/doc/contribute/documenting.md index 4850f3b82626bd2eb7738706e8bf0438dbfb3b60..3a0e226fd187812135015883e8402c60ee781851 100644 --- a/doc/contribute/documenting.md +++ b/doc/contribute/documenting.md @@ -1,4 +1,3 @@ - # Documenting 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. + +*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 OpenSlice's documentation, you need to follow those easy steps: +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: @@ -34,7 +73,7 @@ cd ./documentation git checkout develop ``` -3) Setup a local mkdocs server, using a virtual environment: +3) Setup a local ``mkdocs`` server, using a virtual environment: ```bash python3 -m venv venv @@ -44,7 +83,7 @@ python -m pip install mkdocs-material python -m pip install mike ``` -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**. + +[OCF Web]: https://ocf.etsi.org/ "OCF Web" +[OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation"