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

.. ${PERL} 's#\{bareosConfigResource\}\{(.*?)\}\{(.*?)\}\{(.*?)\}#\n.. code-block:: sh\n    :caption: \1 \2 \3\n#g'   ${DESTFILE}
   perl -i -pe 's#\{bareosConfigResource\}\{(.*)\}\{(.*)\}\{(.*)\}#\n.. code-block:: sh\n    :caption: daemon:\1 resource:\2 name:\3\n#g' ${DESTFILE}

.. 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 documenation, meaning a seperate words (''Archive Device'' instead if ''ArchiveDevice'' or ''archrivedevice'').

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 seperate 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:

.. \newcommand{\resourcetype}[2]{\path|#2|$^{\mbox{\tiny #1}}$}

   Post Conversion Changes
   ${PERL} 's#:raw-latex:`\\resourcetype\{(.*?)\}\{(.*?)\}`#:sup:`\1`\ :strong:`\2`#g'   ${DESTFILE}

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.

Internally, 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``

While the automatically generated may contain a short description (if available in the source code),
the description can be extended by creating of modifying
the corresponding file in the :file:`manually_added_config_directive_descriptions/` subdirectory.

   * :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>

For example:

    dir/job/AlwaysIncrementalJobRetention


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

   Unfortenatly, if this is the case (the reference is wrong (e.g. because of a typo))
   there will be no hint about this during Sphinx build.



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