How is Docutils, Sphinx and Sphinx-Needs organized

Docutils

Author: David Goodger

Link: https://docutils.sourceforge.io

Description: Docutils is an open-source text processing system for processing plain text documentation into useful formats, such as HTML, LaTeX, manual page, OpenDocument, or XML. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plain text markup language.

Advantages: It is possible to extend rst with own directives.

Restriction: Can only process one page.

Sphinx

Link: https://www.sphinx-doc.org

Description: Create intelligent and beautiful documentation …

Advantages: Enhance Docutils to support multi file documentation build with commonly used directives.

Sphinx-Needs

Author: useblocks

Link: https://www.sphinx-needs.com

Description: Sphinx-Needs allows to create, manage and analyze requirements, specifications, test cases and more inside Sphinx-based documentations.

Advantages: Enhance Sphinx to support object like elements with attributes, links, content and process them with functions.

How-to use Sphinx and Sphinx-Needs

You call sphinx-build with input and output folder. All CLI parameters can be found here: https://www.sphinx-doc.org/en/master/man/sphinx-build.html

In the input folder Sphinx expects a index.rst file and normally a conf.py file for the configuration. You can change the path to the configuration even with a sphinx-build parameter -c.

Other useful parameter are:

  • -v, –verbose

  • -W, –fail-on-warning

  • -E, –fresh-env #discard previous build results

  • -a, –write-all #If given, always write all output files

How it is been used with in this repository, you can see here:

 1# from gitlab:
 2# https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml
 3# To contribute improvements to CI/CD templates, please follow the Development guide at:
 4# https://docs.gitlab.com/ee/development/cicd/templates.html
 5# This specific template is located at:
 6# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml
 7
 8# Official language image. Look for the different tagged releases at:
 9# https://hub.docker.com/r/library/python/tags/
10
11#image: danwos/sphinxneeds-latexpdf:latest
12#image: danwos/sphinxneeds:latest
13image: python:latest
14
15# Change pip's cache directory to be inside the project directory since we can
16# only cache local items.
17variables:
18  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
19
20# https://pip.pypa.io/en/stable/topics/caching/
21cache:
22  paths:
23    - .cache/pip
24
25before_script:
26  - python --version ; pip --version ; whoami # For debugging
27  - pip install virtualenv
28  - virtualenv venv
29  - source venv/bin/activate
30  - pip install setuptools
31  # install script requirements
32  # pip install -r ./requirements.txt
33  - apt update
34  - apt-get --yes install graphviz default-jdk
35
36
37
38pages:
39  stage: deploy
40  script:
41    # install documentation requirements
42    - pip install -r ./docs/requirements.txt
43    - sphinx-build -b html --tag project_b ./docs ./public --fail-on-warning --tag tag_Linux --define my_ifconfig='ifconfig_MacOS'
44    # - sphinx-build -b html -t project_b ./docs ./public -vv --show-traceback --fail-on-warning --keep-going
45  artifacts:
46    paths:
47    - public
48  rules:
49    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Definition of a Directive

A directive gives the opportunity to structure information together. Here we use the figure directive to explain how it looks like.

  • Directive Type: “figure”

    1.. figure:: pictures/avatar.png
2   :scale: 150 %
3   :alt: my avatar
4
5   This is the caption of the figure (a simple paragraph).

  • Directive Arguments: “pictures/avatar.png”

    1.. figure:: pictures/avatar.png
2   :scale: 150 %
3   :alt: my avatar
4
5   This is the caption of the figure (a simple paragraph).

  • Directive Options: “:scale: 150 %” and “:alt: my avatar”

    1.. figure:: pictures/avatar.png
2   :scale: 150 %
3   :alt: my avatar
4
5   This is the caption of the figure (a simple paragraph).

  • Directive Content: “This is the caption of the figure (a simple paragraph).”

    1.. figure:: pictures/avatar.png
2   :scale: 150 %
3   :alt: my avatar
4
5   This is the caption of the figure (a simple paragraph).

Example 1: What is a Directive?

.. figure:: pictures/avatar.png
   :scale: 150 %
   :alt: my avatar

   This is the caption of the figure (a simple paragraph).
my avatar

Fig. 18 This is the caption of the figure (a simple paragraph).

Definition of a Role

A role is an inline annotation to get an information or link destination from a script. Here we use the math role to explain how it looks like.

  • Role Type: “math”

    1:math:`(a + b)`

  • Role Argument: “(a + b)”

    1:math:`(a + b)`

Example 2: Docutils Role

:math:`(a + b)` multiplied with :math:`(a - b)` is equal to :math:`a^2 - b^2`.

\((a + b)\) multiplied with \((a - b)\) is equal to \(a^2 - b^2\).