docs (Style Guide): changes after review from Frank Ueberschar

bareos · Apr 5, 2019 · 6bffe44 · 6bffe44
1 parent 5dedc51
commit 6bffe44
Show file tree

Hide file tree

Showing 10 changed files with 147 additions and 83 deletions.
diff --git a/docs/manuals/en/new_main_reference/source/conf.py b/docs/manuals/en/new_main_reference/source/conf.py
@@ -25,13 +25,21 @@
 
 # -- General configuration ------------------------------------------------
 
+# Substitutions have been CamelCase in the past.
+# Now they are all lowercase.
+# CamelCase version can be removed,
+# when they are no longer required.
 rst_epilog = '''
 
 .. |bareosFd| replace:: Bareos File Daemon
+.. |fd| replace:: Bareos File Daemon
 .. |bareosSd| replace:: Bareos Storage Daemon
+.. |sd| replace:: Bareos Storage Daemon
 .. |bareosDir| replace:: Bareos Director
+.. |dir| replace:: Bareos Director
 .. |bconsole| replace:: Bareos Console
 .. |bareosTraymonitor| replace:: Bareos Traymonitor
+.. |traymonitor| replace:: Bareos Traymonitor
 .. |bareosWebui| replace:: Bareos Webui
 .. |webui| replace:: Bareos WebUI
 .. |mysql| replace:: MySQL/MariaDB
@@ -41,11 +49,17 @@
 .. |vsphere| replace:: VMware vSphere
 
 .. |DataManagementAgent| replace:: Data Management Agent
+.. |datamanagementagent| replace:: Data Management Agent
 .. |DataAgent| replace:: Data Agent
+.. |dataagent| replace:: Data Agent
 .. |TapeAgent| replace:: Tape Agent
+.. |tapeagent| replace:: Tape Agent
 .. |RobotAgent| replace:: Robot Agent
+.. |robotagent| replace:: Robot Agent
 .. |ndmpBareos| replace:: :ref:`section-NdmpBareos`
+.. |ndmpbareos| replace:: :ref:`section-NdmpBareos`
 .. |ndmpNative| replace:: :ref:`section-NdmpNative`
+.. |ndmpnative| replace:: :ref:`section-NdmpNative`
 
 '''
 

diff --git a/.../manuals/en/style_guide/source/BareosSpecificFormatting/BareosConfiguration.rst b/.../manuals/en/style_guide/source/BareosSpecificFormatting/BareosConfiguration.rst
@@ -1,8 +1,8 @@
 Bareos Configuration
---------------------
+====================
 
 Bareos Configuration Resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 To display a Bareos specific resource configuration file, use a code block:
 
@@ -50,7 +50,7 @@ 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:
 
@@ -69,13 +69,13 @@ This will get displayed as
 :config:option:`dir/job`
 
 TODO
-^^^^
+~~~~
 
   * needs implmentation
 
 
 Resource Name
-~~~~~~~~~~~~~
+-------------
 
 If you want to display the name of a specific resource, the following formatting should be used::
 
@@ -87,15 +87,15 @@ This will get displayed as
 :config:option:`dir/job = backup-client1`
 
 TODO
-^^^^
+~~~~
 
     * needs implmentation
 
 Resource Directive
-~~~~~~~~~~~~~~~~~~
+------------------
 
 Resource Directive Definition
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The documenation outline for resource directives is autogenerated (by https://github.com/bareos/bareos/blob/master/docs/manuals/scripts/generate-resoure-descriptions.py) and stored into the https://github.com/bareos/bareos/tree/master/docs/manuals/en/new_main_reference/source/autogenerated directory.
 
@@ -125,7 +125,7 @@ the corresponding file in the :file:`config-directive-description/` subdirectory
 
 
 Reference to a Resource Directive
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to display a resource directive, the following formatting should be used::
 
@@ -147,17 +147,17 @@ For example:
 
 .. note::
 
-   If the link target :ref:`BareosSpecificFormatting/BareosConfiguration:Resource Directive Definition` is unknown,
-   the displayed text will not alter.
+   If the reference to a Resource Directive does not match a  :ref:`BareosSpecificFormatting/BareosConfiguration:Resource Directive Definition`,
+   the displayed text will look the same, but there will be no hyperlink behind it.
 
-   Unfortenatly, if a reference is wrong (e.g. because of a typo)
+   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.
 
 
 
 
 Resource Directive With Value
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to display a resource directive along with its value, the following formatting should be used::
 
@@ -169,6 +169,6 @@ This will get displayed as
 :config:option:`dir/job/AlwaysIncrementalJobRetention = 900`
 
 TODO
-''''
+^^^^
 
   * needs implmentation
diff --git a/docs/manuals/en/style_guide/source/BareosSpecificFormatting/BareosHostNames.rst b/docs/manuals/en/style_guide/source/BareosSpecificFormatting/BareosHostNames.rst
@@ -22,7 +22,7 @@ The output should look like this:
 :strong:`client1.example.com`
 
 
-.. csv-table:: NDMP Names
+.. csv-table:: Host Names
    :header: "Host name", "Description"
 
    ":strong:`bareos-dir.example.com`",     "Bareos Director host"

diff --git a/docs/manuals/en/style_guide/source/BareosSpecificFormatting/BareosVersions.rst b/docs/manuals/en/style_guide/source/BareosSpecificFormatting/BareosVersions.rst
@@ -43,7 +43,7 @@ This will be displayed as:
 Note
 ----
 
-``:sinceVersion:`` is a legacy role. Sphinx itself offer
+``:sinceVersion:`` is a legacy role. Sphinx itself offers
 
   * https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
   * https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged

diff --git a/...anuals/en/style_guide/source/BareosSpecificFormatting/DocumentFileStructure.rst b/...anuals/en/style_guide/source/BareosSpecificFormatting/DocumentFileStructure.rst
@@ -1,5 +1,5 @@
 Document File Structure
-------------------------
+=======================
 
 The document is splitted chapter wise in different rst files.
 The document is put together using the toctree directive.
@@ -21,27 +21,42 @@ The document is put together using the toctree directive.
       * SectionNameInCamelCase2.rst (content)
       * ...
 
+    * ChapterNameInCamelCaseWithOnlyOneSingleChapter3.rst (content)
+
+    * ChapterNameInCamelCaseWithOnlyOneSingleChapter4.rst (content)
+
     * ...
 
   * include/
 
     * autogenerated/
     * config/
     * images/
-
-
-A toctree file contains normally only a heading (to structure the document)
-and the toctree directive to include the subordinated files (sections),
-from a directory with the same name as the toctree file itself.
 
-The Section RST files do contain the real content.
-There file name is also given from the first heading.
-The first heading should be underlined by "=", like::
+The file name is also given from the first heading.
+
+The first heading should be underlined by ``=``, like::
 
    Section Heading
    ===============
 
 Please read :ref:`RestOverview:Sections` to get known to the section ordering conventions.
+
+All documents should only contain one highest level section (underlined by ``=``).
+
+If there are more highest level headings required,
+the file should be replaced by a toctree document
+and the content should be splitted into multiple files
+and placed in the matching subdirectory.
+
+.. A toctree file contains normally only a heading (to structure the document)
+   and the toctree directive to include the subordinated files (sections),
+   from a directory with the same name as the toctree file itself.
+
+Files included by toctree will be inserted as one section level below the section header of the including document.
+
+.. The section reST files do contain the real content.
+
 
 .. warning::
 

diff --git a/docs/manuals/en/style_guide/source/BareosSpecificFormatting/Release.rst b/docs/manuals/en/style_guide/source/BareosSpecificFormatting/Release.rst
@@ -1,5 +1,5 @@
 Releases
-########
+========
 
 Release Notes - Stable Version
 ------------------------------
@@ -43,12 +43,12 @@ Output:
 This refers to :ref:`bareos-17.2.7`\ .
 
 
-Release Notes - Unstable Version
---------------------------------
+.. Release Notes - Unstable Version
+   --------------------------------
 
-TODO: required?
-
-If you want to display the release notes of a bareos unstable release, the following formatting should be used:
+   TODO: required?
+   
+  If you want to display the release notes of a bareos unstable release, the following formatting should be used:
 
 .. \newcommand{\releasenoteUnstable}[2]{
     \subsection*{\textit{bareos-#1 (unstable)}}
@@ -57,21 +57,13 @@ If you want to display the release notes of a bareos unstable release, the follo
     #2
    }
 
-* Heading: ``bareos-<release_version> (unstable)``
-* Mandatory information to be provided in release notes:
-   1. Code Release
-   2. Database Version
-   3. Release Ticket
-   4. Download URL
-   5. Beta Release
-
 
 
 URLs
-####
+----
 
 Release URL - Bareos.org
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to display the release download URL from the Bareos.org site, the following formatting should be used:
 
@@ -86,7 +78,7 @@ http://download.bareos.org/bareos/release/18.2/
 
 
 Release URL - Bareos.com
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to display the release download URL from the Bareos.com site, the following formatting should be used:
 
@@ -102,7 +94,7 @@ https://download.bareos.com/bareos/release/18.2/
 
 
 Contributions Download URL
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you want to display the download URL of plugins available on Bareos.org, the following formatting should be used:
 

diff --git a/docs/manuals/en/style_guide/source/CommonNames.rst b/docs/manuals/en/style_guide/source/CommonNames.rst
@@ -1,5 +1,5 @@
 Common Names
-############
+============
 
 Specific strings are used again and again in the Bareos documentation.
 
@@ -8,28 +8,27 @@ Here we define how these name should be written (upper or lower case, in one wor
 Text subsitutions can be defined in :file:`conf.py` file.
 
 Bareos Names
-============
-
+------------
 
 +----------------------------------------+-------------------------------------------+
 |      **Text to be Displayed**          |           **Text Formatting**             |
 +----------------------------------------+-------------------------------------------+
 | Bareos 	                         | Bareos                                    |
 +----------------------------------------+-------------------------------------------+
-| |bareosDir| 	                         | ``|bareosDir|``                           |
+| |dir| 	                         | ``|dir|``                                 |
 +----------------------------------------+-------------------------------------------+
-| |bareosSd|		                 | ``|bareosSd|``                            |
+| |sd|	         	                 | ``|sd|``                                  |
 +----------------------------------------+-------------------------------------------+
-| |bareosFd|                             | ``|bareosSd|``       		     |
+| |fd|                                   | ``|fd|``       		             |
 +----------------------------------------+-------------------------------------------+
 | |bconsole|                             | ``|bconsole|``                            |
 +----------------------------------------+-------------------------------------------+
-| |bareosWebui|     			 | ``|bareosWebui|``                         |
+| |webui|         			 | ``|webui|``                               |
 +----------------------------------------+-------------------------------------------+
-| |bareosTraymonitor|                    | ``|bareosTraymonitor|``                   |
+| |traymonitor|                          | ``|traymonitor|``                         |
 +----------------------------------------+-------------------------------------------+
 
-The name **Bareos** should always be written as capital B (except in technical terms like URLs, releases (bareos-18.2.5) or host names).
+The name **Bareos** should always be written with capital B (except in technical terms like URLs, releases (bareos-18.2.5) or host names).
 
 
 Bareos Paths and Filenames
@@ -64,26 +63,26 @@ NDMP
 .. csv-table:: NDMP Names
    :header: "Text to be Displayed", "Text Formatting"
 
-   |DataManagementAgent|,     ``|DataManagementAgent|``
-   |DataAgent|,               ``|DataAgent|``
-   |TapeAgent|,               ``|TapeAgent|``
-   |RobotAgent|,              ``|RobotAgent|``
-   |ndmpBareos|,              ``|ndmpBareos|``
-   |ndmpNative|,              ``|ndmpNative|``
+   "Data Management Agent", "Data Management Agent"
+   "Data Agent",            "Data Agent"
+   "Tape Agent",            "Tape Agent"
+   "Robot Agent",           "Robot Agent"
+   |ndmpbareos|,            ``|ndmpbareos|``
+   |ndmpnative|,            ``|ndmpnative|``
 
 .. _section-NdmpBareos:
 
 NDMP_BAREOS
 ~~~~~~~~~~~
 
-This is only a fake section to demonstrate ``|ndmpBareos|``. Ignore it.
+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.
+This is only a fake section to demonstrate ``|ndmpnative|``. Ignore it.
 
 
 Products