.. documentation:


Documentation
=============

This is the description, how the "Logistics" Project is documented with these pages.

|

Sphinx
------

This documentation is based on `Sphinx <https://www.sphinx-doc.org/en/master/index.html>`_. Sphinx is a tool to create and publish documentation for various projects as websites in form of HTML pages. But it can also publish ePub, LaTeX, Texinfo and plain text. It was originally created for the `Python documentation <https://docs.python.org/3/>`_, and it has many facilities for the documentation of software projects in a range of languages. A good reference ist the german book `Software-Dokumentation mit Sphinx <https://drive.google.com/open?id=1P2VvXLuytWxCsixT7lPZ0D7H9iXYMijX&usp=drive_fs>`_.

Sphinx uses per default `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ as its markup language, and many of its features come from the possibilities of reStructuredText and its parsing and translating suite, see also `Docutils text processing system <https://docutils.sourceforge.io/>`_ .

A good local installed editor is `Sublime Text <https://www.sublimetext.com>`_.

.. toctree::
   :maxdepth: 6

   sphinx/sphinx

|

Markdown
--------

Instead of reStructuredText, also `Markdown <https://daringfireball.net/projects/markdown/>`_ could be used as the markup language for the layout of the pages. For more details of how to integrate markdown pages in Sphinx see `Sphinx Documentation about Markdown <https://www.sphinx-doc.org/en/master/usage/markdown.html>`_ and `Recommonmark <https://recommonmark.readthedocs.io/en/latest/>`_.


|

Pandoc
------

`Pandoc <https://pandoc.org/index.html>`_ is a universal document converter to convert files from one markup format into another.

Command to convert Markdown document to reStructuredText document (name of the file is "example.md"), including an automatically generated table of contents in the output document (--toc):

.. code-block:: shell

   pandoc --toc example.md --from markdown --standalone --to rst -o example.rst

Command to convert rst (reStructuredText) document to Markdown (name of the file is "index.rst"):

.. code-block:: shell

   pandoc -f rst index.rst -t markdown_mmd -o index.md

Command to convert WORD document to RST (name of the file is "guidelines.docx"):

.. code-block:: shell

   pandoc -f docx guidelines.docx -t rst -o guidelines.rst

Command to convert WORD document to Markdown (name of the file is "guidelines.docx"):

.. code-block:: shell

  pandoc -f docx guidelines.docx -t markdown_mmd -o guidelines.md