docs (Style Guide): merged Documentation Style Guide into Main Docume…

…ntation
bareos · Apr 5, 2019 · faa80fe · faa80fe
1 parent a8e512a
commit faa80fe
Show file tree

Hide file tree

Showing 49 changed files with 119 additions and 919 deletions.
diff --git a/docs/manuals/en/new_main_reference/latex-scan.py b/docs/manuals/en/new_main_reference/latex-scan.py
@@ -145,6 +145,11 @@ def __init__(self):
                 'flags':   re.VERBOSE,
                 'replace': r'/include/images/\1.*\n'
             },
+            'LOWERBAREOS': {
+                'pattern': r' _LOWERBAREOS-',
+                'flags':   re.VERBOSE,
+                'replace': r'_bareos-'
+            },
             'EnvBareosConfigResource': {
                 'pattern': r'::\n\n(\s*)\\begin{bareosConfigResource}{(.*?)}{(.*?)}{(.*?)}\s*\n(.*?)\n\s*\\end{bareosConfigResource}',
                 'flags':   self.regexOpts, 
@@ -1280,7 +1285,7 @@ def user(item):
     #
     @staticmethod
     def variable(item):
-        item.replace(r'**{0}**'.format(*item.getParameters()))
+        item.replace(r'``{0}``\ '.format(*item.getParameters()))
 
     @staticmethod
     def volume(item):

diff --git a/docs/manuals/en/new_main_reference/pre_conversion_changes.sh b/docs/manuals/en/new_main_reference/pre_conversion_changes.sh
@@ -49,9 +49,9 @@ for FILENAME in ${SOURCEFILES}; do
 \
     | perl -0 -pe 's|\\subsubsubsection\{|\\paragraph\{|g' \
 \
-    | perl -0 -pe 's|\\releasenoteSection\{(.*?)\}|\\section*{\1}\n\n|smg' \
+    | perl -0 -pe 's|\\releasenoteSection\{(.*?)\}|\\section{\1}|smg' \
 \
-    | perl -0 -pe 's|\\releasenote\{(.*?)\}|\\subsection*{bareos-\1}\n\\index[general]{bareos-\1!Release Notes}\n\n|smg' \
+    | perl -0 -pe 's|\\releasenote\{(.*?)\}|\\subsection{bareos-\1}\n\n\\label{LOWERBAREOS-\1}\n\n\\index[general]{bareos-\1!Release Notes}\n\n|smg' \
 \
     | perl -0 -pe 's|\\releasenoteUnstable\{(.*?)\}|\\subsection*{\\textit{bareos-\1 (unstable)}}\n\n|smg' \
 \

diff --git a/docs/manuals/en/new_main_reference/source/DocumentationStyleGuide.rst b/docs/manuals/en/new_main_reference/source/DocumentationStyleGuide.rst
@@ -0,0 +1,13 @@
+
+Documentation Style Guide
+=========================
+
+
+.. toctree::
+
+   /DocumentationStyleGuide/Introduction.rst
+   /DocumentationStyleGuide/RestOverview.rst
+   /DocumentationStyleGuide/CommonNames.rst
+   /DocumentationStyleGuide/SpecificFormatting.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting.rst
+   /DocumentationStyleGuide/Gotchas.rst
diff --git a/.../new_main_reference/source/DocumentationStyleGuide/BareosSpecificFormatting.rst b/.../new_main_reference/source/DocumentationStyleGuide/BareosSpecificFormatting.rst
@@ -0,0 +1,14 @@
+Bareos Specific Formatting
+==========================
+
+.. toctree::
+
+   /DocumentationStyleGuide/BareosSpecificFormatting/DocumentFileStructure.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/BareosHostNames.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/Bconsole.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/BareosLogging.rst   
+   /DocumentationStyleGuide/BareosSpecificFormatting/Limitation.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/Ticket.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/BareosVersions.rst
+   /DocumentationStyleGuide/BareosSpecificFormatting/Release.rst
diff --git a/...pecificFormatting/BareosConfiguration.rst → ...pecificFormatting/BareosConfiguration.rst b/...pecificFormatting/BareosConfiguration.rst → ...pecificFormatting/BareosConfiguration.rst
@@ -9,12 +9,12 @@ 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:: /example/code-block-bareosconfig.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/code-block-bareosconfig.rst.inc
    :language: none
 
 which will be displayed as
 
-.. include:: /example/code-block-bareosconfig.rst.inc
+.. include:: /DocumentationStyleGuide/example/code-block-bareosconfig.rst.inc
 
 
 The *caption* shows the relevant path where to expect the configuration resource:
@@ -147,7 +147,7 @@ For example:
 
 .. note::
 
-   If the reference to a Resource Directive does not match a  :ref:`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))

diff --git a/...eosSpecificFormatting/BareosHostNames.rst → ...eosSpecificFormatting/BareosHostNames.rst b/...eosSpecificFormatting/BareosHostNames.rst → ...eosSpecificFormatting/BareosHostNames.rst
@@ -15,11 +15,11 @@ If you want to display a hostname, the following formatting should be followed:
 
 .. code-block:: sh
 
-   :strong:`client1.example.com`
+   :strong:`host1.example.com`
 
 The output should look like this:
 
-:strong:`client1.example.com`
+:strong:`host1.example.com`
 
 
 .. csv-table:: Host Names
@@ -29,4 +29,5 @@ The output should look like this:
    ":strong:`bareos-sd.example.com`",      "Bareos Storage Daemon host, if only one Storage Daemon is used."
    ":strong:`bareos-sd1.example.com`, :strong:`bareos-sd2.example.com`, ...", "Bareos Storage Daemon host, if multiple Storage Daemons are used."
    ":strong:`bareos-sd-tape.example.com`", "Bareos Storage Daemon with a specific backend."
-   ":strong:`client1.example.com`, :strong:`client2.example.com`, ...", "Bareos File Daemon"
+   ":strong:`host.example.com`", "An arbitrary system, without special requirements."
+   ":strong:`host1.example.com`, :strong:`host2.example.com`, ...", "Bareos File Daemon"
diff --git a/...areosSpecificFormatting/BareosLogging.rst → ...areosSpecificFormatting/BareosLogging.rst b/...areosSpecificFormatting/BareosLogging.rst → ...areosSpecificFormatting/BareosLogging.rst
@@ -5,8 +5,8 @@ If you want to display Bareos specific logs, use following formatting:
 
 .. ${PERL} 's#\{logging\}\{(.*)\}#\n.. code-block:: sh\n    :caption: \1\n#g'   ${DESTFILE}
 
-.. literalinclude:: /example/code-block-bareoslog.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/code-block-bareoslog.rst.inc
 
 The output will look like this:
 
-.. include:: /example/code-block-bareoslog.rst.inc
+.. include:: /DocumentationStyleGuide/example/code-block-bareoslog.rst.inc
diff --git a/...reosSpecificFormatting/BareosVersions.rst → ...reosSpecificFormatting/BareosVersions.rst b/...reosSpecificFormatting/BareosVersions.rst → ...reosSpecificFormatting/BareosVersions.rst
@@ -32,12 +32,12 @@ and
 
 Example:
 
-.. literalinclude:: /example/sinceVersion-configuration-scheme.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/sinceVersion-documentation-sphinx.rst.inc
    :language: none
 
 This will be displayed as:
 
-.. include:: /example/sinceVersion-configuration-scheme.rst.inc
+.. include:: /DocumentationStyleGuide/example/sinceVersion-documentation-sphinx.rst.inc
 
 
 Note

diff --git a/...rce/BareosSpecificFormatting/Bconsole.rst → ...ide/BareosSpecificFormatting/Bconsole.rst b/...rce/BareosSpecificFormatting/Bconsole.rst → ...ide/BareosSpecificFormatting/Bconsole.rst
@@ -44,12 +44,12 @@ Bconsole session
 
 If you want to show complete Bareos console session, then it needs to be put in a code block.
 
-.. literalinclude:: /example/code-block-bconsole-configure-add.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/code-block-bconsole-configure-add.rst.inc
    :language: none
 
 The output will look like this:
 
-.. include:: /example/code-block-bconsole-configure-add.rst.inc
+.. include:: /DocumentationStyleGuide/example/code-block-bconsole-configure-add.rst.inc
 
 A prompt is indicated by ''*''.
 

diff --git a/...cificFormatting/DocumentFileStructure.rst → ...cificFormatting/DocumentFileStructure.rst b/...cificFormatting/DocumentFileStructure.rst → ...cificFormatting/DocumentFileStructure.rst
@@ -40,7 +40,7 @@ The first heading should be underlined by ``=``, like::
    Section Heading
    ===============
 
-Please read :ref:`RestOverview:Sections` to get known to the section ordering conventions.
+Please read :ref:`DocumentationStyleGuide/RestOverview:Sections` to get known to the section ordering conventions.
 
 All documents should only contain one highest level section (underlined by ``=``).
 
@@ -61,10 +61,10 @@ Files included by toctree will be inserted as one section level below the sectio
 .. warning::
 
    Changing the file names will change the published URLs
-   and the autosectionlabels (see :ref:`RestOverview:Cross-linking markup`).
+   and the autosectionlabels (see :ref:`DocumentationStyleGuide/RestOverview:Cross-linking markup`).
    So link used from external source
    and also some internal links will no longer work.
-   See :ref:`Gotchas:toctree vs include`.
+   See :ref:`DocumentationStyleGuide/Gotchas:toctree vs include`.
 
    (Even without changing the file name,
    changing the section name will also break links.)
diff --git a/...e/BareosSpecificFormatting/Limitation.rst → ...e/BareosSpecificFormatting/Limitation.rst b/...e/BareosSpecificFormatting/Limitation.rst → ...e/BareosSpecificFormatting/Limitation.rst
@@ -14,9 +14,9 @@ The short description should be as short as possible, as it will get part of the
 
 Example:
 
-.. literalinclude:: /example/limitation-vm-configuration.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/limitation-example.rst.inc
    :language: none
 
 This will be displayed as:
 
-.. include:: /example/limitation-vm-configuration.rst.inc
+.. include:: /DocumentationStyleGuide/example/limitation-example.rst.inc
diff --git a/...urce/BareosSpecificFormatting/Release.rst → ...uide/BareosSpecificFormatting/Release.rst b/...urce/BareosSpecificFormatting/Release.rst → ...uide/BareosSpecificFormatting/Release.rst
@@ -14,16 +14,16 @@ If you want to display the release notes of a Bareos stable release, use the fol
     #2
    }
 
-.. literalinclude:: /example/releasenotes-template.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/releasenotes-template.rst.inc
 
 Example:
 
-.. literalinclude:: /example/releasenotes.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/releasenotes-17.2.7.rst.inc
 
 
-Output:
+See the output at :ref:`bareos-17.2.7`\ .
 
-.. include:: /example/releasenotes.rst.inc
+.. COMMENT include:: /DocumentationStyleGuide/example/releasenotes.rst.inc
 
 
 

diff --git a/...ource/BareosSpecificFormatting/Ticket.rst → ...Guide/BareosSpecificFormatting/Ticket.rst b/...ource/BareosSpecificFormatting/Ticket.rst → ...Guide/BareosSpecificFormatting/Ticket.rst
@@ -6,12 +6,12 @@ bugs.bareos.org
 
 If you want to reference to a ticket in https://bugs.bareos.org, the following formatting should be used:
 
-.. literalinclude:: /example/ticket.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/ticket.rst.inc
    :language: none
 
 This will be displayed as:
 
-.. include:: /example/ticket.rst.inc
+.. include:: /DocumentationStyleGuide/example/ticket.rst.inc
 
 Github
 ------
@@ -28,22 +28,22 @@ Pull request
 
 Refer to a Github Pull request by:
 
-.. literalinclude:: /example/github-pull-request.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/github-pull-request.rst.inc
    :language: none
 
 This will be displayed as:
 
-.. include:: /example/github-pull-request.rst.inc
+.. include:: /DocumentationStyleGuide/example/github-pull-request.rst.inc
 
 
 Commit
 ~~~~~~
 
 Refer to a Github Commit by:
 
-.. literalinclude:: /example/github-commit.rst.inc
+.. literalinclude:: /DocumentationStyleGuide/example/github-commit.rst.inc
    :language: none
 
 This will be displayed as:
 
-.. include:: /example/github-commit.rst.inc
+.. include:: /DocumentationStyleGuide/example/github-commit.rst.inc
diff --git a/...als/en/style_guide/source/CommonNames.rst → ...e/DocumentationStyleGuide/CommonNames.rst b/...als/en/style_guide/source/CommonNames.rst → ...e/DocumentationStyleGuide/CommonNames.rst
@@ -70,20 +70,6 @@ NDMP
    |ndmpbareos|,            ``|ndmpbareos|``
    |ndmpnative|,            ``|ndmpnative|``
 
-.. _section-NdmpBareos:
-
-NDMP_BAREOS
-~~~~~~~~~~~
-
-This is only a fake section to demonstrate ``|ndmpbareos|``. Ignore it.
-
-.. _section-NdmpNative:
-
-NDMP_NATIVE
-~~~~~~~~~~~
-
-This is only a fake section to demonstrate ``|ndmpnative|``. Ignore it.
-
 
 Products
 --------

diff --git a/...manuals/en/style_guide/source/Gotchas.rst → ...ource/DocumentationStyleGuide/Gotchas.rst b/...manuals/en/style_guide/source/Gotchas.rst → ...ource/DocumentationStyleGuide/Gotchas.rst
@@ -13,7 +13,7 @@ or run :program:`make clean` before.
 Not shown text
 --------------
 
-When using :ref:`RestOverview:Directives`, they are prepanded by the comment directives: ''.. ''
+When using :ref:`DocumentationStyleGuide/RestOverview:Directives`, they are prepanded by the comment directives: ''.. ''
 
 For this reason, any mispelled directives will not be shown at all (and not even are warning is shown during sphinx-build).
 
@@ -29,14 +29,19 @@ For example, config directives can be defined and later on referenced by::
 
    :config:option:`...`
 
-If the link target :ref:`BareosSpecificFormatting/BareosConfiguration:Reference to a Resource Directive` is unknown,
+If the link target :ref:`DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration:Reference to a Resource Directive` is unknown,
 the displayed text will not alter.
 
 There will not even be a warning during Sphinx build,
 making it really hard to find typos in this kind of references.
 
-TODO: example
+* valid reference:
 
+  * :config:option:`dir/job/AlwaysIncrementalJobRetention`
+
+* invalid reference:
+
+  * :config:option:`dir/job/ThisIsaDeadEntry`
 
 toctree vs include
 ------------------
@@ -75,4 +80,4 @@ toctree
 Don't use the ``:options:`` role, as this tries to refers to a option definition, which we don't have.
 Also, as we document different programs, using option would require to prefix it with the program name, see https://www.sphinx-doc.org/en/1.7/domains.html#directive-program.
 
-This only applies to ``:options:`` without domain. We do you ``:config:option:`` in :ref:`BareosSpecificFormatting/BareosConfiguration:Bareos Configuration`.
+This only applies to ``:options:`` without domain. We do you ``:config:option:`` in :ref:`DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration:Bareos Configuration`.
diff --git a/...ls/en/style_guide/source/Introduction.rst → .../DocumentationStyleGuide/Introduction.rst b/...ls/en/style_guide/source/Introduction.rst → .../DocumentationStyleGuide/Introduction.rst
@@ -1,7 +1,7 @@
 Introduction
 ============
 
-This is a complete guide to the language and style conventions used for Bareos Main Reference and Documentation. The Sphinx tool has been used to produce a presentable documentation using the reStructuredText (reST) files present in https://github.com/bareos/bareos/tree/master/docs/manuals/en/new_main_reference/source\ .
+This is a complete guide to the language and style conventions used for Bareos Documentation. The Sphinx tool has been used to produce a presentable documentation using the reStructuredText (reST) files present in https://github.com/bareos/bareos/tree/master/docs/manuals/en/new_main_reference/source\ .
 
 The primary output format is HTML.
 It is doubtfull, is PDFs can be created easily (internally, Sphinx would convert to Latex first, and than use Latex to create the PDF).