NS8 documentation

Sphinx documentation sources for NS8 documentations.

Under the root directory there are some specials files:

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.

How to contribute

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:

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:

NethServer 8 documentation

Other

Language:Python 79.7%Language:Makefile 20.3%