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 plaintext documentation into useful formats, such as HTML, LaTeX, man-pages, OpenDocument, or XML. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext 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 repo, 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.

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\).

  • Role Type: “math”

    1:math:`(a + b)`

  • Role Argument: “(a + b)”

    1:math:`(a + b)`