Document File Structure
=======================

The document is splitted chapter wise in different rst files.
The document is put together using the toctree directive.

  * _extensions/
  * index.rst (toctree)

    * ChapterNameInCamelCase1.rst (toctree)
    * ChapterNameInCamelCase1/

      * SectionNameInCamelCase1.rst (content)
      * SectionNameInCamelCase2.rst (content)
      * ...

    * ChapterNameInCamelCase2.rst (toctree)
    * ChapterNameInCamelCase2/

      * SectionNameInCamelCase1.rst (content)
      * SectionNameInCamelCase2.rst (content)
      * ...

    * ChapterNameInCamelCaseWithOnlyOneSingleChapter3.rst (content)

    * ChapterNameInCamelCaseWithOnlyOneSingleChapter4.rst (content)

    * ...

  * include/

    * autogenerated/
    * config/
    * images/

The file name is also given from the first heading.

The first heading should be underlined by ``=``, like::

   Section Heading
   ===============

Please read :ref:`DocumentationStyleGuide/RestOverview:Sections` to get known to the section ordering conventions.

All documents should only contain one highest level section (underlined by ``=``).

If there are more highest level headings required,
the file should be replaced by a toctree document
and the content should be splitted into multiple files
and placed in the matching subdirectory.

.. A toctree file contains normally only a heading (to structure the document)
   and the toctree directive to include the subordinated files (sections),
   from a directory with the same name as the toctree file itself.

Files included by toctree will be inserted as one section level below the section header of the including document.

.. The section reST files do contain the real content.


.. warning::

   Changing the file names will change the published URLs
   and the autosectionlabels (see :ref:`DocumentationStyleGuide/RestOverview:Cross-linking markup`).
   So link used from external source
   and also some internal links will no longer work.
   See :ref:`DocumentationStyleGuide/Gotchas:toctree vs include`.

   (Even without changing the file name,
   changing the section name will also break links.)

.. note::

   Do not use filesystem links in the documentation.

   The Bareos documentation is not generated by the normal :command:`sphinx-build` command,
   but by the :command:`sphinx-versioning` (2.2.1) command.
   This command however does not handle filesystem links.
