Sphinx documentation sources for NS8 documentations.
Under the root directory there are some specials files:
- conf.py: Sphinx configuration
- Makefile: Sphinx build makefile
- index.rst: document structure
All other .rst files are chapters of the manual. If you wish to add a new
chapter, create a new file and add it to the index.rst file.
The easiest way to contribute is by forking and editing the repository directly on GitHub:
- Create a GitHub account if you don't already have it
- Go to https://github.com/NethServer/ns8-docs and fork the project
- You can now edit any page using GitHub web interface and see a live preview of the output
- When you're done, simply create a new pull request
- A new automatic build is launched after the pull request is merged by a developer
While editing, please follow the guidelines below.
The document must start with a title such as
============== Document title ==============
Make sure to add only one first-level title for each rst file.
Next headers levels are:
First level =========== Second level ------------ Third level ^^^^^^^^^^^ Fourth level ~~~~~~~~~~~~
To create cross-references set a label before headers, with -section suffix:
.. _mytitle-section: My title --------
In other documents refer to "My title" with the :ref: command:
More informations are explained on :ref:`mytitle-section`
Use the * character for unordered list
* First element * Second element
Use a definition list when describing fields
My field
This is my description
A field description can also contain a bullet list
My field
This is my description
* First element
* Second element
Highlight important words
This is and *important* word.
Add notes with
.. note:: Highlight this text
Add warnings with
.. warning:: Warning text fragments
You can find more info about RST Inline Markup here: rst-cheatsheet
Use semantic markup whenever possible. Recommended RST roles are:
- guilabel
- file
- command
- menuselection
Use a spell checker program before submitting a pull request. For instance run
hunspell -d en_US <filename>
Whenever there are modifications, a build process will be launched from CI.
If you wish to build documentation locally on your machine, make sure to install the Sphinx package.
On Fedora 37 or later use:
sudo dnf install python3-sphinx python3-pip make
Then clone the repository, enter the inside the cloned directory and install all required extra modules
git clone https://github.com/NethServer/ns8-docs.git cd ns8-docs pip install -r requirements.txt
FInally, build the doc:
make html
Generate po files for a new language:
make gettext sphinx-intl update -p _build/gettext -l it
When editing documents, please remind the following guidelines:
- https://www.writethedocs.org/blog/newsletter-december-2016/#simplifying-and-tightening-your-writing
- https://www.writethedocs.org/blog/newsletter-october-2022/#gerunds-in-headings
- https://www.writethedocs.org/blog/newsletter-september-2022/#when-to-use-acronyms
- https://www.writethedocs.org/blog/newsletter-november-2019/#you-sing-the-second-person-in-documentation
- https://www.writethedocs.org/blog/newsletter-may-2018/#using-imperatives-in-documentation
- https://www.writethedocs.org/blog/newsletter-july-2017/#documenting-unlabeled-buttons
- https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips