To display a Bareos specific resource configuration file, use a code block:
/DocumentationStyleGuide/example/code-block-bareosconfig.rst.inc
which will be displayed as
The caption shows the relevant path where to expect the configuration resource:
- <daemon>
.d/
(bareos-dir.d, bareos-sd.d, bareos-fd.d, ...)- <resource type>
/
- <resource name>
.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 /include/config/
subdirectory of the documentation.
Normally, these snippets contain a complete Bareos configuration resource.
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
:configdir/job
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
:configdir/job = backup-client1
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
dir/job/AlwaysIncrementalJobRetention
.../Configuration/Director.html#config-Dir_Job_AlwaysIncrementalJobRetention
:config
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 manually_added_config_directive_descriptions/
subdirectory, e.g.:
:config
dir/job/AlwaysIncrementalJobRetention
manually_added_config_directive_descriptions/dir-job-AlwaysIncrementalJobRetention.rst.inc
:config
fd/client/AllowBandwidthBursting
manually_added_config_directive_descriptions/fd-client-AllowBandwidthBursting.rst.inc
If you want to display a resource directive, the following formatting should be used:
:config:option:`dir/job/AlwaysIncrementalJobRetention`
This will get displayed as
:configdir/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 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: ...
).
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
:configdir/job/AlwaysIncrementalJobRetention = 900