=======================
Linux@BFH.ch Styleguide
=======================

Document Structure and index
============================

Index.rst and table of contents
-------------------------------

A document structure consists of a folder, a :code:`index.rst` and subdocuments. Subdocuments are refered in the index.rst with the toctree directive. All subdocuments have a document title (:code:`=` chars below and on upper line). These titles will be shown in toc's (table of contents) as well by crossreferencing documents.

.. code-block:: rest

   =====================
   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.

Crossreferencing to a another document
--------------------------------------

FIXME

.. code-block:: rest

   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 :doc:`document </software/gnupg/index>` and has the title :doc:`/software/gnupg/index`.
Usage of direct document title is as well possible :doc:`index`.

Referencing to a section
------------------------

FIXME

.. code-block:: rest

   .. _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 Objects
==============

Code or other monospaced objects
--------------------------------

Inline paths or files can use of the code directive::

  This file is at :code:`/etc/hosts`.

This file is at :code:`/etc/hosts`.

----

Or by using double apostrophe::

  This file is at ``/etc/hosts``.

This file is at ``/etc/hosts``.

Raw html
--------

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 |stuff|.

.. |stuff| raw:: html

   <em>emphasized text containing a
      <a href="http://example.org">hyperlink</a> and
         <tt>inline literals</tt></em>

Footnotes
---------

For footnotes (`ref <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#footnotes>`_), 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:

.. code-block:: rest

   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 (``[#]_``).

Symbols
-------

.. include:: <isonum.txt>

.. code-block:: rest

  .. include:: <isonum.txt>

   This is a foo |rarr| bar test.

This is a foo |rarr| bar test.

HTML
====

Pure HTML can be embedded by the ``.. raw::`` directive.

.. code-block:: rest

   .. raw:: html

      <div class="col-lg-4">
          dingens
      </div>

Block Objects
=============

Code
----

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

  .. code-block:: bash

     rm -Rf *

.. code-block:: bash

   rm -Rf *

Horizontal rule
---------------

A horizontal line (<hr />)::

  A block of text.

  ----

  A second block of text.

A block of text.

----

A second block of text.

Admonitions
===========

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

.. admonition:: Example

   foo bar

Custom CSS
==========

Inline (span element)
---------------------

.. code:: rest

   .. role:: small

   This is a example :small:`small span` text.

.. role:: small

This is a example :small:`small span` text.

Block
-----

.. code:: rest

   .. rst-class:: small

      This is a example small text block.

.. rst-class:: small

   This is a example small text block.