Merge pull request #1761

docs: improve handling of ResourceItem descriptions
bareos · Apr 10, 2024 · 9634259 · 9634259
2 parents 89eab59 + f3e6b11
commit 9634259
Show file tree

Hide file tree

Showing 11 changed files with 100 additions and 102 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -56,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - PR template: remove backport hints [PR #1762]
 - python-bareos: use TLS-PSK from core ssl module (available since Python >= 3.13) [PR #1756]
 - [percona-xtrabackup] prevent High memory usage for no reason (IO_CLOSE) [PR #1724]
+- docs: improve handling of ResourceItem descriptions [PR #1761]
 
 ### Removed
 - plugins: remove old deprecated postgres plugin [PR #1606]
@@ -138,5 +139,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [PR #1746]: https://github.com/bareos/bareos/pull/1746
 [PR #1752]: https://github.com/bareos/bareos/pull/1752
 [PR #1756]: https://github.com/bareos/bareos/pull/1756
+[PR #1761]: https://github.com/bareos/bareos/pull/1761
 [PR #1762]: https://github.com/bareos/bareos/pull/1762
 [unreleased]: https://github.com/bareos/bareos/tree/master
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -93,6 +93,8 @@ if(BUILD_UNIVERSAL_CLIENT)
 endif()
 
 option(ENABLE_WEBUI "Build with WEBUI" ON)
+option(docs-only "Build only the documentation" OFF)
+option(docs-build-json "Update the configuration schema JSON files" OFF)
 
 if(docs-build-json)
   # check for wrong combinations of build flags

diff --git a/core/src/lib/resource_item.h b/core/src/lib/resource_item.h
@@ -3,7 +3,7 @@
 
    Copyright (C) 2000-2010 Free Software Foundation Europe e.V.
    Copyright (C) 2011-2012 Planets Communications B.V.
-   Copyright (C) 2013-2023 Bareos GmbH & Co. KG
+   Copyright (C) 2013-2024 Bareos GmbH & Co. KG
 
    This program is Free Software; you can redistribute it and/or
    modify it under the terms of version three of the GNU Affero General Public
@@ -44,7 +44,8 @@ struct ResourceItem {
    * start_version: directive has been introduced in this version
    * end_version:   directive is deprecated since this version */
   const char* versions;
-  /* description of the directive, used for the documentation.
+  /* short description of the directive, in plain text,
+   * used for the documentation.
    * Full sentence.
    * Every new directive should have a description. */
   const char* description;

diff --git a/core/src/lib/tls_resource_items.h b/core/src/lib/tls_resource_items.h
@@ -3,7 +3,7 @@
 
    Copyright (C) 2000-2010 Free Software Foundation Europe e.V.
    Copyright (C) 2011-2012 Planets Communications B.V.
-   Copyright (C) 2013-2023 Bareos GmbH & Co. KG
+   Copyright (C) 2013-2024 Bareos GmbH & Co. KG
 
    This program is Free Software; you can redistribute it and/or
    modify it under the terms of version three of the GNU Affero General Public
@@ -38,16 +38,16 @@
   { "EnableKtls", CFG_TYPE_BOOL, ITEM(res, enable_ktls_), 0, CFG_ITEM_DEFAULT, "false", \
      NULL, "If set to \"yes\", Bareos will allow the SSL implementation to use " \
      "Kernel TLS. " }, \
-  { "TlsCipherList", CFG_TYPE_STDSTRDIR, ITEM(res, cipherlist_), 0, CFG_ITEM_PLATFORM_SPECIFIC, NULL, \
-     NULL, "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"}, \
-  { "TlsCipherSuites", CFG_TYPE_STDSTRDIR, ITEM(res, ciphersuites_), 0, CFG_ITEM_PLATFORM_SPECIFIC, NULL, \
-     NULL, "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`." \
+  { "TlsCipherList", CFG_TYPE_STDSTR, ITEM(res, cipherlist_), 0, CFG_ITEM_PLATFORM_SPECIFIC, NULL, \
+     NULL, "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command." \
+     " Leftmost element has the highest priority."}, \
+  { "TlsCipherSuites", CFG_TYPE_STDSTR, ITEM(res, ciphersuites_), 0, CFG_ITEM_PLATFORM_SPECIFIC, NULL, \
+     NULL, "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command." \
     " Leftmost element has the highest priority." \
-    " Currently only SHA256 ciphers are supported."},						\
+    " Currently only SHA256 ciphers are supported."}, \
   { "TlsDhFile", CFG_TYPE_STDSTRDIR, ITEM(res, tls_cert_.dhfile_), 0, 0, NULL, \
      NULL, "Path to PEM encoded Diffie-Hellman parameter file. " \
-     "If this directive is specified, DH key exchange will be used for " \
-     "the ephemeral keying, " \
+     "If this directive is specified, DH key exchange will be used for the ephemeral keying, " \
      "allowing for forward secrecy of communications." }, \
   { "TlsProtocol", CFG_TYPE_STDSTR, ITEM(res, protocol_), 0, CFG_ITEM_PLATFORM_SPECIFIC, NULL, \
      "20.0.0-", "OpenSSL Configuration: Protocol"}
@@ -72,6 +72,5 @@
   { "TlsAllowedCn", CFG_TYPE_STR_VECTOR, ITEM(res, tls_cert_.allowed_certificate_common_names_), 0, 0, NULL, \
      NULL, "\"Common Name\"s (CNs) of the allowed peer certificates." }
 
-
 /* clang-format on */
 #endif  // BAREOS_LIB_TLS_RESOURCE_ITEMS_H_
diff --git a/docs/manuals/scripts/generate-resource-descriptions.py b/docs/manuals/scripts/generate-resource-descriptions.py
@@ -258,15 +258,14 @@ def getDefaultValue(self, data):
         return default
 
     def getDescription(self, data):
-        description = ""
-        if data.get("description"):
-            # Some descriptions contains text surrounded by '*'.
-            # This regex puts backticks around these texts.
-            description_rst = re.sub(
-                "(\*.*?\*)", ":strong:`\\1`", data.get("description")
-            )
-            description = self.indent(description_rst, 3)
-        return description
+        description = data.get("description", "")
+        # Raise exception, when descriptions look like RST formatting.
+        if re.search(r"\*\*|`", description) is not None:
+            raise RuntimeError(f"Description is not plain text: '{description}'")
+        # Some descriptions contains text surrounded by '*'.
+        # This regex puts backticks around these texts.
+        description_rst = re.sub(r"(\*.*?\*)", r":strong:`\1`", description)
+        return self.indent(description_rst, 3)
 
     def getConvertedResourceDirectives(self, daemon, resourcename):
         logger = logging.getLogger()

diff --git a/...source/DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration.rst b/...source/DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration.rst
@@ -10,9 +10,6 @@ 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
 
@@ -29,7 +26,7 @@ The *caption* shows the relevant path where to expect the configuration resource
 
 The prefix path is not shown, as it is platform specific.
 
-The directives should be written like shown in the documenation, meaning a separate words (''Archive Device'' instead if ''ArchiveDevice'' or ''archrivedevice'').
+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.
 
@@ -58,11 +55,6 @@ 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`
@@ -95,9 +87,13 @@ Resource Directive
 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.
+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.
+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`
@@ -108,9 +104,12 @@ From extern, the URL to access them is
 
       * ``.../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.
+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`
 
@@ -140,19 +139,15 @@ 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`,
+   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.
-
+   In such cases, Sphinx issues a warning during build
+   (``WARNING: config:option reference target not found: ...``).
 
 
 .. _documentationstyleguide/bareosspecificformatting/bareosconfiguration:resource directive with value:

diff --git a/docs/manuals/source/include/autogenerated/bareos-dir-config-schema.json b/docs/manuals/source/include/autogenerated/bareos-dir-config-schema.json
@@ -229,18 +229,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",
@@ -527,18 +527,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",
@@ -1761,18 +1761,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",
@@ -2515,18 +2515,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",

diff --git a/docs/manuals/source/include/autogenerated/bareos-fd-config-schema.json b/docs/manuals/source/include/autogenerated/bareos-fd-config-schema.json
@@ -101,18 +101,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",
@@ -391,18 +391,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",
@@ -681,18 +681,18 @@
           "description": "If set to \"yes\", Bareos will allow the SSL implementation to use Kernel TLS. "
         },
         "TlsCipherList": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "List of valid TLSv1.2 and lower Ciphers; see :command:`openssl ciphers`"
+          "description": "Colon separated list of valid TLSv1.2 and lower Ciphers; see \"openssl ciphers\" command. Leftmost element has the highest priority."
         },
         "TlsCipherSuites": {
-          "datatype": "DIRECTORY",
+          "datatype": "STRING",
           "code": 0,
           "platform_specific": true,
           "equals": true,
-          "description": "Colon separated list of valid TLSv1.3 Ciphers; see :command:`openssl ciphers -s -tls1_3`. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
+          "description": "Colon separated list of valid TLSv1.3 Ciphers; see \"openssl ciphers -s -tls1_3\" command. Leftmost element has the highest priority. Currently only SHA256 ciphers are supported."
         },
         "TlsDhFile": {
           "datatype": "DIRECTORY",