From 6e8af2e71bcb304c53a01eeaff5d08b7cea5ee3b Mon Sep 17 00:00:00 2001 From: Joerg Steffens Date: Fri, 8 Feb 2019 19:11:29 +0100 Subject: [PATCH] docs: style guide: add hints about section ordering ... and information of differences between inlcude and toctree. Renamed file to circumwent sphinx problems with include. --- .../manuals/en/style_guide/source/general.rst | 35 ++++++++++++------- .../source/include/{file.rst => file.rst.inc} | 0 docs/manuals/en/style_guide/source/index.rst | 1 + .../manuals/en/style_guide/source/trouble.rst | 32 +++++++++++++++++ 4 files changed, 56 insertions(+), 12 deletions(-) rename docs/manuals/en/style_guide/source/include/{file.rst => file.rst.inc} (100%) create mode 100644 docs/manuals/en/style_guide/source/trouble.rst diff --git a/docs/manuals/en/style_guide/source/general.rst b/docs/manuals/en/style_guide/source/general.rst index 2aab5585e5a..b9f0fe8c936 100644 --- a/docs/manuals/en/style_guide/source/general.rst +++ b/docs/manuals/en/style_guide/source/general.rst @@ -169,29 +169,40 @@ Alternatively, you can reference any label (not just section titles) if you provide the link text ``:ref:`link text ```. - Sections -------- -From https://devguide.python.org/documenting/#sections. - Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text: :: - ================= + ################# This is a heading - ================= + ################# -Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, here is a suggested convention: +Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this is our convention: * ``#`` with overline, for parts -* ``*`` with overline, for chapters -* ``=``, for sections -* ``-``, for subsections +* ``=`` for chapters +* ``-``, for sections +* ``~``, for subsections * ``^``, for subsubsections -* ``"``, for paragraphs +* ``'``, for paragraphs + +This convention has be introduced from the conversion of thw original LaTex source to RST, +as :program:`pandoc` has created RST file with this section markers (except of parts, which are not created at all). +.. note:: + + With RST, there is no leaving out a section level. + If you write a chapter it is not possible to continue with a paragraph. + Instead the next section must be of the type section. + + If you try to do it overwise (chapter 1 ``=`` -> paragraph ``'``), + the ''paragraph'' is treated as a section. + And if you continue by another chapter (in the same file) (chapter 2 ``=`` -> section ``-``), + :program:`sphinx-build` got confused and at least produces a warning (`Title level inconsistent`) + and possibly renders the result incorrectly. File/Directory/Path @@ -212,11 +223,11 @@ Backslahes (Windows paths) ``\`` have to written as ``\\``: The output should look like this: -.. include:: include/file.rst +.. include:: include/file.rst.inc The formatting looks a follows: -.. literalinclude:: include/file.rst +.. literalinclude:: include/file.rst.inc diff --git a/docs/manuals/en/style_guide/source/include/file.rst b/docs/manuals/en/style_guide/source/include/file.rst.inc similarity index 100% rename from docs/manuals/en/style_guide/source/include/file.rst rename to docs/manuals/en/style_guide/source/include/file.rst.inc diff --git a/docs/manuals/en/style_guide/source/index.rst b/docs/manuals/en/style_guide/source/index.rst index 10317b218f9..4d738a7f64b 100644 --- a/docs/manuals/en/style_guide/source/index.rst +++ b/docs/manuals/en/style_guide/source/index.rst @@ -17,3 +17,4 @@ Bareos Style Guide seldom_text images releases + trouble diff --git a/docs/manuals/en/style_guide/source/trouble.rst b/docs/manuals/en/style_guide/source/trouble.rst new file mode 100644 index 00000000000..f862c1809b7 --- /dev/null +++ b/docs/manuals/en/style_guide/source/trouble.rst @@ -0,0 +1,32 @@ +Trouble +======= + +toctree vs include +------------------ + +include +""""""" + +If a source file add another file via **include**, +it will be integrated into the original source file (and not handled as a seperate file). + +As sphinx-build scans all matchin files during the build process, it takes toctree inclusion into account, but not plain **include** statements. As result, it will see the content of the included file twice: one as included file as part of the source file, once by the scan process during the build. Sphinx will then complain about double defined heading and references. + +To avoid this, included files should use a different extension as the normal files (included by toctree). + + * Extention of the master file and files included by **toctree**: ``*.rst`` + * Extention of files included by **include**: ``*.rst.inc`` + +.. + + does include keep the document structre as toctree does? + + +toctree +""""""" + +* When using (nested) toctrees, make sure to define a section header above it. Otherwise the header line of the result document will show **** in the hierarchie of headings. + +* All files included by toctree start at the same section level. If the sections of a document should start at a lower level, a nested toctree element is needed. + +* **Important**: files names of files included via toctree are part of the URL of the document. That means, they are also part of the URL of the references/sections. And the URL will change when a section is moved to another place. Therefore inclusion via **toctree should be avoided**!