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

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

Warning

Changing the file names will change the published URLs and the autosectionlabels (see Cross-linking markup). So link used from external source and also some internal links will no longer work. See 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 sphinx-build command, but by the sphinx-versioning (2.2.1) command. This command however does not handle filesystem links.