ReStructured Directives – practical documentation

:link: more about the reST syntax here

:link: a quick reference about reST

:link: a excellent reference about reST and sphinx here

Include a file into another file

:warning: NOt working for .md files! :warning:

.. include:: <yourfile.format>

MarkDown Vs. reStructured

sintassi reST:

.. directivename:: arguments
   :key1: val1
   :key2: val2

   This is
   directive content

in MarkDown diventa

\```{directivename} arguments
---
key1: val1
key2: val2
---
This is
directive content
\```

TocTree directive

:point_up: a reST file can contain more than one .. toctree:: directive.

general syntax:

.. toctree::
	...
	:option: value
	...
	
	...
	file.name
	...

file name syntax:

  • path/of/the/file.tp prints the title of the page and the link

  • this page <path/of/the/file.tp> print this page with the link to the page

ToC tree in markdown

\```{toctree} 
---
maxdepth: 1
caption: this is a toc
glob:
hidden:
---

... link ...
link name </link/path>

\```

Index Template

:point_up: reSt is truly horrible. Use the reST only for indexing the documentation. And nothing else.

.. _your-tag:

page title
==========

.. toctree::
	:maxdepth: 1
	:caption: ToC title
	:titlesonly:
	:glob:
	:hidden:
	
	...
	link text <./path/link.format>
	...

the page can be referred using both :ref:<your-tag> and :any:<your-tag>. WITH BACKTICKS!

Add some code

from Python

This directive inserts the entire documentation related to the py file you’re referring to. Just one instructor for generating the documentation.

:point_up: in Sphinx, you say where to generate the documentation, pointing the page with this directive. In Doxygen instead, the file system is fixed.

.. automodule:: your_py_file
    :members:
    :noindex:

from Doxygen/Breathe

same observations as before for what concerns the cpp files.

.. doxygenfile:: your-cpp-file.cpp
    :project: your-project-name

Images

.. image:: someimage.png
   :class: with-border with-shadow
   :alt: Textual alternative to the image

tabs

:link: see tabs in reST

.. tabs::

   .. group-tab:: bash

      .. code-block:: bash

         touch example-project-directory/public/FIRST_INSTALL

   .. group-tab:: powershell

      .. code-block:: powershell

         echo $null >> public/FIRST_INSTALL

UML diagrams

here

Graphs with graphiz

extensions = ['sphinx.ext.graphviz']

see the example on the Internet.

Graphs with plantUML

see in particular plantUML on gitHub

install the extension:

pip install sphinxcontrib-plantuml

extension:

extensions = ['sphinxcontrib.plantuml']

plantUML and markdown

\```{uml} 
@startuml

@endtuml
\```