diff --git a/doc/contribute/documenting.md b/doc/contribute/documenting.md new file mode 100644 index 0000000000000000000000000000000000000000..4850f3b82626bd2eb7738706e8bf0438dbfb3b60 --- /dev/null +++ b/doc/contribute/documenting.md @@ -0,0 +1,57 @@ + +# Documenting + +OpenCAPIF's documentation runs on [MkDocs](https://www.mkdocs.org/). + +## Eligibility + +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 + +[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. + +## Getting Started + +To contribute to OpenSlice's documentation, you need to follow those easy steps: + +1) Clone the [Documentation repository](https://labs.etsi.org/rep/ocf/documentation) with: + +```bash +git clone https://labs.etsi.org/rep/ocf/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 local mkdocs server, using a virtual environment: + +```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 +``` + +4) Wait for all downloads to finish and start the mkdocs server: + +```bash +mkdocs serve +``` + +5) Document (and commit)! 😊 + +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. diff --git a/doc/gettingstarted/howtorun.md b/doc/gettingstarted/howtorun.md index 135affbbcd60b11de40129abe99434f216fe5ffc..3eac55bf95a21f4a913fae7d70ed26eda91b79e2 100644 --- a/doc/gettingstarted/howtorun.md +++ b/doc/gettingstarted/howtorun.md @@ -1,3 +1,5 @@ +# How to Run + - [Downloading the project](#downloading-the-project) - [1. Create a folder to download the project](#1-create-a-folder-to-download-the-project) - [2. Download the deployment script](#2-download-the-deployment-script) diff --git a/mkdocs.yml b/mkdocs.yml index aa15c1ed66425563b17f5dfec62ef6604f47dc9b..c1c0cbc7e8a2c665b91aa1f324441163b7620d23 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,4 +82,6 @@ nav: - Test Plan: ./testing/testplan/README.md - Robot Framework: ./testing/robotframework/README.md - Postman: ./testing/postman/README.md + - Contributing: + - Documentation: ./contribute/documenting.md - FAQ: ./FAQ.md