A document structure consists of a folder, a index.rst and subdocuments. Subdocuments are refered in the index.rst with the toctree directive. All subdocuments have a document title (= chars below and on upper line). These titles will be shown in toc’s (table of contents) as well by crossreferencing documents.
=====================
Example Documentation
=====================
Example introdution text.
.. toctree::
:maxdepth: 2
installation
configuration
usage
best-practice
ressources
This example has several subsections in files named installation.rst etc.
FIXME
This is a sample reference to another :doc:`document </software/gnupg/index>` and has the title :doc:`/software/gnupg/index`.
Usage of direct document titles is as well possible :doc:`index`.
This is a sample reference to another document and has the title GnuPG. Usage of direct document title is as well possible Sphinx.
FIXME
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Hint
See more at http://www.sphinx-doc.org/en/stable/markup/inline.html#role-ref
Inline paths or files can use of the code directive:
This file is at :code:`/etc/hosts`.
This file is at /etc/hosts.
Or by using double apostrophe:
This file is at ``/etc/hosts``.
This file is at /etc/hosts.
How to insert inline raw html:
Here is some |stuff|.
.. |stuff| raw:: html
<em>emphasized text containing a
<a href="http://example.org">hyperlink</a> and
<tt>inline literals</tt></em>
Here is some emphasized text containing a hyperlink and inline literals.
For footnotes (ref), use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading, like so:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_).
Pure HTML can be embedded by the .. raw:: directive.
.. raw:: html
<div class="col-lg-4">
dingens
</div>
By a preceeding block and double colons:
By a preceeding block and double colons::
rm -Rf *
By a preceeding block and double colons:
rm -Rf *
By a a preceeding directive:
.. code-block:: bash
rm -Rf *
rm -Rf *
A horizontal line (<hr />):
A block of text.
----
A second block of text.
A block of text.
A second block of text.
Usage of specific admonitions like “attention”, “caution”, “danger”, “error”, “hint”, “important”, “note”, “tip”, “warning”, “admonition”:
.. NOTE:: Beware of killer rabbits
Note
Beware of killer rabbits
Usage by your own title:
.. admonition:: Example
foo bar
Example
foo bar