.. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:bareos configuration:

Bareos Configuration
====================

.. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:bareos configuration resource:

Bareos Configuration Resource
-----------------------------

To display a Bareos specific resource configuration file, use a code block:

.. literalinclude:: /DocumentationStyleGuide/example/code-block-bareosconfig.rst.inc
   :language: none

which will be displayed as

.. include:: /DocumentationStyleGuide/example/code-block-bareosconfig.rst.inc


The *caption* shows the relevant path where to expect the configuration resource:

   #. <daemon>\ :file:`.d/` (bareos-dir.d, bareos-sd.d, bareos-fd.d, ...)
   #. <resource type>\ :file:`/`
   #. <resource name>\ :file:`.conf`

The prefix path is not shown, as it is platform specific.

The directives should be written like shown in the documentation, meaning a separate words (''Archive Device'' instead of ''ArchiveDevice'' or ''archivedevice'').

Use ``...`` to indicate left out directives not relevant for the example.


.. note::

   Remember to start each code-block line by 3 indenting spaces. However, the code itself is indented by the rules of the resource (2 spaces for Bareos configuration resources).


If the content is a separate file, use

::

   .. literalinclude:: /include/config/bareos-sd.d/device/FileStorage.conf
      :language: bareosconfig
      :caption: bareos-dir.d/job/consolidate.conf

All configuration snippets should be located in the :file:`/include/config/` subdirectory of the documentation.

Normally, these snippets contain a complete Bareos configuration resource.



Resource Type
-------------

If you want to display a resource type, the following formatting should be used:

If you want to display the name of a specific resource, the following formatting should be used::

   :config:option:`dir/job`


This will get displayed as

:config:option:`dir/job`

.. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:resource name:

Resource Name
-------------

If you want to display the name of a specific resource, the following formatting should be used::

   :config:option:`dir/job = backup-client1`


This will get displayed as

:config:option:`dir/job = backup-client1`


Resource Directive
------------------

.. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:resource directive definition:

Resource Directive Definition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The documentation outline for resource directives is autogenerated
(by https://github.com/bareos/bareos/blob/master/docs/manuals/scripts/generate-resource-descriptions.py)
and stored into the
https://github.com/bareos/bareos/tree/master/docs/manuals/source/include/autogenerated/
directory.

Inside the documentation, they can be referenced by the ``:config:option:`` directive.
From extern, the URL to access them is

   * :config:option:`dir/job/AlwaysIncrementalJobRetention`

      * ``.../Configuration/Director.html#config-Dir_Job_AlwaysIncrementalJobRetention``

   * :config:option:`fd/client/AllowBandwidthBursting`

      * ``.../Configuration/FileDaemon.html#config-Fd_Client_AllowBandwidthBursting``

The automatically generated descriptions
are defined in the ``C++`` source code (as ``ResourceItem.description``).
They have to be short (1-2 short sentences) and can only contain plain text.
Longer descriptions or descriptions that require formatting have to be written
by creating of modifying the corresponding file in the
:file:`manually_added_config_directive_descriptions/` subdirectory, e.g.:

   * :config:option:`dir/job/AlwaysIncrementalJobRetention`

      * :file:`manually_added_config_directive_descriptions/dir-job-AlwaysIncrementalJobRetention.rst.inc`

   * :config:option:`fd/client/AllowBandwidthBursting`

      * :file:`manually_added_config_directive_descriptions/fd-client-AllowBandwidthBursting.rst.inc`



.. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:reference to a resource directive:

Reference to a Resource Directive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to display a resource directive, the following formatting should be used::

   :config:option:`dir/job/AlwaysIncrementalJobRetention`


This will get displayed as

:config:option:`dir/job/AlwaysIncrementalJobRetention`

The signature must be given as::

   <dir|sd|fd|console>/<resourcetype_lower_case>/<DirectiveInCamelCase>


.. note::

   If the reference to a Resource Directive does not match a
   :ref:`DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration:Resource Directive Definition`,
   the displayed text will look the same, but there will be no hyperlink behind it.

   In such cases, Sphinx issues a warning during build
   (``WARNING: config:option reference target not found: ...``).


.. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:resource directive with value:

Resource Directive With Value
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to display a resource directive along with its value, the following formatting should be used::

   :config:option:`dir/job/AlwaysIncrementalJobRetention = 900`


This will get displayed as

:config:option:`dir/job/AlwaysIncrementalJobRetention = 900`
