From 8fc08fcbc93a4b8b121700be945a6d0e1030f3e0 Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 09:58:11 +0000 Subject: [PATCH 1/8] Align documentation guidelines --- doc/contributing/documenting.md | 124 ++++++++++++++++++++++---------- requirements.txt | 5 ++ 2 files changed, 93 insertions(+), 36 deletions(-) create mode 100644 requirements.txt diff --git a/doc/contributing/documenting.md b/doc/contributing/documenting.md index f5a14e5b..ffac2908 100644 --- a/doc/contributing/documenting.md +++ b/doc/contributing/documenting.md @@ -1,4 +1,3 @@ - # Documenting OpenSlice's documentation runs on [MkDocs](https://www.mkdocs.org/). @@ -8,71 +7,124 @@ OpenSlice's documentation runs on [MkDocs](https://www.mkdocs.org/). Documenting OpenSlice 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 does it work? + +There are 2 ways to upgrade documentation published on the [OSL Documentation] website: + + * Push any change on **develop** branch will force update of the **develop** version on the [OSL Documentation] website; + * Create a tag, this will create a version with the tag name on the [OSL 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 [OSL 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 + - Deployment examples: deployment_examples.md + - History: history.md + - OpenSlice under ETSI: etsi_osl.md + - Getting Started: + - Deployment: + - Introduction: ./getting_started/deployment/introduction.md + - Docker Compose: ./getting_started/deployment/docker_compose.md + - Kubernetes: ./getting_started/deployment/kubernetes.md + - Portals: ./getting_started/portals.md +[...] +``` + +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 OpenSlice and should reference the version (useful shortcut is ``{{{ documentation_version }}}``). + ## Getting Started -To contribute to OpenSlice's documentation, you need to follow those easy steps: +To contribute to OpenSlice's documentation, you need to follow these easy steps: 1) Clone the [Documentation repository](https://labs.etsi.org/rep/osl/documentation) with: ```bash -git clone https://labs.etsi.org/rep/osl/documentation.git +git clone https://labs.etsi.org/rep/ocf/documentation.git ``` -2) Checkout the develop branch (incoming contributions are only accepted to the develop branch): +2) Checkout the develop branch (incoming contributions are only accepted to the **develop** branch): ```bash cd ./documentation git checkout develop ``` -3) Setup a local mkdocs server, using a virtual environment +3) Setup a virtual environment: -=== "Linux + macOS" +* On Linux/macOS: - ``` bash - python3 -m venv venv - source venv/bin/activate - ``` - ``` bash - python -m pip install mkdocs - python -m pip install mkdocs-material - python -m pip install mkdocs-glightbox - python -m pip install mkdocs-markdownextradata-plugin - python -m pip install mike - ``` + ```bash + python3 -m venv venv # Linux/macOS + source venv/bin/activate #Linux/macOS + ``` -=== "Windows" +* On Windows: - ``` bash - python -m venv venv - venv\Scripts\activate - ``` - ``` bash - python -m pip install mkdocs - python -m pip install mkdocs-material - python -m pip install mkdocs-glightbox - python -m pip install mkdocs-markdownextradata-plugin - python -m pip install mike - ``` + ```bash + python -m venv venv # Windows + venv\Scripts\activate # Windows + ``` +4) Setup a local ``mkdocs`` server by installing requirements: -4) Wait for all downloads to finish and start the mkdocs server +```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 (and commit)! 😊 +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/osl/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 PR 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 **OpenSlice** code repository is ready for a new release, we need to follow these steps (made by a **TSC Member**): -Before committing, you should make sure that the local mkdcocs server's terminal is not producing any INFO/WARNING message regarding your contributions. +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! -> 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. +[OSL Web]: https://osl.etsi.org/ "OSL Web" +[OSL Documentation]: https://osl.etsi.org/documentation/ "OSL Documentation" diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..10a0c2fe --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +mkdocs +mkdocs-material +mkdocs-glightbox +mkdocs-markdownextradata-plugin +mike \ No newline at end of file -- GitLab From e2c89bfd415d97d4f292a14e5e2ed38ee337a2e4 Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 09:58:31 +0000 Subject: [PATCH 2/8] Update file documenting.md --- doc/contributing/documenting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing/documenting.md b/doc/contributing/documenting.md index ffac2908..5545cbb1 100644 --- a/doc/contributing/documenting.md +++ b/doc/contributing/documenting.md @@ -114,7 +114,7 @@ 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); 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 PR request towards **develop**; +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. @@ -123,7 +123,7 @@ To update the documentation properly during development, follow those additional When **OpenSlice** code repository is ready for a new release, we need to follow these steps (made by a **TSC Member**): -1. Create a PR from **develop** towards **main**; +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! [OSL Web]: https://osl.etsi.org/ "OSL Web" -- GitLab From f1a0baa6654ea3464e5c8d13ae6fca627f955182 Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 10:22:23 +0000 Subject: [PATCH 3/8] Update 6 files - /doc/contributing/developing.md - /doc/contributing/documenting.md - /doc/contributing/wishlist.md - /doc/contribute/developing.md - /doc/contribute/wishlist.md - /doc/contribute/documenting.md --- doc/{contributing => contribute}/developing.md | 0 doc/{contributing => contribute}/documenting.md | 16 ++++++++-------- doc/{contributing => contribute}/wishlist.md | 0 3 files changed, 8 insertions(+), 8 deletions(-) rename doc/{contributing => contribute}/developing.md (100%) rename doc/{contributing => contribute}/documenting.md (96%) rename doc/{contributing => contribute}/wishlist.md (100%) diff --git a/doc/contributing/developing.md b/doc/contribute/developing.md similarity index 100% rename from doc/contributing/developing.md rename to doc/contribute/developing.md diff --git a/doc/contributing/documenting.md b/doc/contribute/documenting.md similarity index 96% rename from doc/contributing/documenting.md rename to doc/contribute/documenting.md index 5545cbb1..9708c6c8 100644 --- a/doc/contributing/documenting.md +++ b/doc/contribute/documenting.md @@ -77,17 +77,17 @@ git checkout develop * On Linux/macOS: - ```bash - python3 -m venv venv # Linux/macOS - source venv/bin/activate #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 - ``` +```bash +python -m venv venv # Windows +venv\Scripts\activate # Windows +``` 4) Setup a local ``mkdocs`` server by installing requirements: diff --git a/doc/contributing/wishlist.md b/doc/contribute/wishlist.md similarity index 100% rename from doc/contributing/wishlist.md rename to doc/contribute/wishlist.md -- GitLab From d0ad37eca0f6c0c1b1582f59b242afbdc3dfa245 Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 10:41:32 +0000 Subject: [PATCH 4/8] Update file README.md --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..189587a2 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# Documentation + +This respository contains the documentation of TeraFlowSDN. + +## Getting Started + +Please check the relevant document at [documenting.md](doc/contribute/documenting.md). \ No newline at end of file -- GitLab From 32553b3bb1cc30c3fc2cfa72d8adf5ebed620067 Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 10:41:56 +0000 Subject: [PATCH 5/8] Update file README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 189587a2..5faeb715 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Documentation -This respository contains the documentation of TeraFlowSDN. +This respository contains the documentation of OpenSlice. ## Getting Started -- GitLab From 429b990f6e92029bf502066a74c85dcdb9e89b4a Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 10:45:30 +0000 Subject: [PATCH 6/8] Update file mkdocs.yml --- mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 72ab0b92..505d3615 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -193,7 +193,7 @@ nav: - NFV API: ./architecture/nfvapi.md - Issue management: ./architecture/issuemgt.md - Central logging: ./architecture/centrallog.md - - Contributing to OSL: - - Developing: ./contributing/developing.md - - Documenting: ./contributing/documenting.md + - Contribute: + - Developing: ./contribute/developing.md + - Documenting: ./contribute/documenting.md - Terminology: terminology.md -- GitLab From 98752ab32ed4c33c8c497745a76c5051a38a9599 Mon Sep 17 00:00:00 2001 From: Julien Satti Date: Thu, 20 Feb 2025 13:27:09 +0000 Subject: [PATCH 7/8] Iterate on the feedback from TECH call --- README.md | 44 ++++++++++++++++++++- doc/contribute/documenting.md | 74 ++++++++--------------------------- 2 files changed, 60 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 5faeb715..db18ccfa 100644 --- a/README.md +++ b/README.md @@ -4,4 +4,46 @@ This respository contains the documentation of OpenSlice. ## Getting Started -Please check the relevant document at [documenting.md](doc/contribute/documenting.md). \ No newline at end of file +Please check the relevant document at [documenting.md](doc/contribute/documenting.md). + +## How does it work? + +There are 2 ways to upgrade documentation published on the [OSL Documentation] website: + + * Push any change on **develop** branch will force update of the **develop** version on the [OSL Documentation] website; + * Create a tag, this will create a version with the tag name on the [OSL 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 [OSL 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 + - Deployment examples: deployment_examples.md + - History: history.md + - OpenSlice under ETSI: etsi_osl.md + - Getting Started: + - Deployment: + - Introduction: ./getting_started/deployment/introduction.md + - Docker Compose: ./getting_started/deployment/docker_compose.md + - Kubernetes: ./getting_started/deployment/kubernetes.md + - Portals: ./getting_started/portals.md +[...] +``` + +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 OpenSlice and should reference the version (useful shortcut is ``{{{ documentation_version }}}``). diff --git a/doc/contribute/documenting.md b/doc/contribute/documenting.md index 9708c6c8..ad8963dd 100644 --- a/doc/contribute/documenting.md +++ b/doc/contribute/documenting.md @@ -14,48 +14,6 @@ Documenting OpenSlice 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 does it work? - -There are 2 ways to upgrade documentation published on the [OSL Documentation] website: - - * Push any change on **develop** branch will force update of the **develop** version on the [OSL Documentation] website; - * Create a tag, this will create a version with the tag name on the [OSL 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 [OSL 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 - - Deployment examples: deployment_examples.md - - History: history.md - - OpenSlice under ETSI: etsi_osl.md - - Getting Started: - - Deployment: - - Introduction: ./getting_started/deployment/introduction.md - - Docker Compose: ./getting_started/deployment/docker_compose.md - - Kubernetes: ./getting_started/deployment/kubernetes.md - - Portals: ./getting_started/portals.md -[...] -``` - -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 OpenSlice and should reference the version (useful shortcut is ``{{{ documentation_version }}}``). - ## Getting Started To contribute to OpenSlice's documentation, you need to follow these easy steps: @@ -63,7 +21,7 @@ To contribute to OpenSlice's documentation, you need to follow these easy steps: 1) Clone the [Documentation repository](https://labs.etsi.org/rep/osl/documentation) with: ```bash -git clone https://labs.etsi.org/rep/ocf/documentation.git +git clone https://labs.etsi.org/rep/osl/documentation.git ``` 2) Checkout the develop branch (incoming contributions are only accepted to the **develop** branch): @@ -73,25 +31,23 @@ cd ./documentation git checkout develop ``` -3) Setup a virtual environment: +3) Setup a local ``mkdocs`` server with a virtual environment: -* On Linux/macOS: +=== "Linux + macOS" -```bash -python3 -m venv venv # Linux/macOS -source venv/bin/activate #Linux/macOS -``` + ``` bash + python3 -m venv venv + source venv/bin/activate + ``` -* On Windows: +=== "Windows" -```bash -python -m venv venv # Windows -venv\Scripts\activate # Windows -``` - -4) Setup a local ``mkdocs`` server by installing requirements: + ``` bash + python -m venv venv + venv\Scripts\activate + ``` -```bash +``` bash python -m pip install -r requirements.txt ``` @@ -128,3 +84,7 @@ When **OpenSlice** code repository is ready for a new release, we need to follow [OSL Web]: https://osl.etsi.org/ "OSL Web" [OSL Documentation]: https://osl.etsi.org/documentation/ "OSL Documentation" + +## Learn more + +If you wish to learn more about the documentation system, check [this](https://labs.etsi.org/rep/osl/documentation/README.md) link. \ No newline at end of file -- GitLab From ba71569bed196e8532d94a8b696dc0e03854a5eb Mon Sep 17 00:00:00 2001 From: Kostis Trantzas Date: Fri, 21 Feb 2025 17:16:38 +0200 Subject: [PATCH 8/8] Moving documentation version update from documenting.md to README.md --- README.md | 10 ++++++++++ doc/contribute/documenting.md | 14 ++------------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index db18ccfa..004a1892 100644 --- a/README.md +++ b/README.md @@ -47,3 +47,13 @@ Please take a moment to understand the current structure of the documentations a ### Main Page The page shown first is at **doc/index.md**. That page should be updated with the latest changes of OpenSlice and should reference the version (useful shortcut is ``{{{ documentation_version }}}``). + +### Release a New Version of the Documentation + +When **OpenSlice** 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! + +[OSL Web]: https://osl.etsi.org/ "OSL Web" +[OSL Documentation]: https://osl.etsi.org/documentation/ "OSL Documentation" \ No newline at end of file diff --git a/doc/contribute/documenting.md b/doc/contribute/documenting.md index ad8963dd..84cb8aae 100644 --- a/doc/contribute/documenting.md +++ b/doc/contribute/documenting.md @@ -10,7 +10,7 @@ Documenting OpenSlice is limited to active contributors. So, if you: 2. wish to contribute to it; 3. you're ready! -## 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. @@ -75,16 +75,6 @@ To update the documentation properly during development, follow those additional > 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 **OpenSlice** 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! - -[OSL Web]: https://osl.etsi.org/ "OSL Web" -[OSL Documentation]: https://osl.etsi.org/documentation/ "OSL Documentation" - ## Learn more -If you wish to learn more about the documentation system, check [this](https://labs.etsi.org/rep/osl/documentation/README.md) link. \ No newline at end of file +If you wish to learn more about the documentation system, check [this link](https://labs.etsi.org/rep/osl/documentation/README.md). \ No newline at end of file -- GitLab