From 4ddc36118d1a6b0fed9043c8c66c0ff82c9ead85 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Tue, 30 Jan 2024 17:40:13 +0100 Subject: [PATCH] [TASK] Remove "common pitfalls" Displaying wrong syntax in order to teach someone is generally not considered best practise. Also some of these are specific to sphinx or outdated spinx versions. --- Documentation/GeneralConventions/Format.rst | 1 - .../WritingReST/CommonPitfalls/Headers.rst | 52 ---------- .../WritingReST/CommonPitfalls/Hyperlinks.rst | 71 -------------- .../WritingReST/CommonPitfalls/Indents.rst | 49 ---------- .../WritingReST/CommonPitfalls/Index.rst | 24 ----- .../CommonPitfalls/InlineStyle.rst | 45 --------- .../WritingReST/CommonPitfalls/Lists.rst | 94 ------------------- Documentation/WritingReST/Index.rst | 4 - .../Reference/Content/BoldItalic.rst | 10 +- .../Reference/Lists/BulletLists.rst | 63 +------------ 10 files changed, 4 insertions(+), 409 deletions(-) delete mode 100644 Documentation/WritingReST/CommonPitfalls/Headers.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Indents.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Index.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/InlineStyle.rst delete mode 100644 Documentation/WritingReST/CommonPitfalls/Lists.rst diff --git a/Documentation/GeneralConventions/Format.rst b/Documentation/GeneralConventions/Format.rst index 296cc6e6..a3b95f90 100644 --- a/Documentation/GeneralConventions/Format.rst +++ b/Documentation/GeneralConventions/Format.rst @@ -88,7 +88,6 @@ readthedocs:: * indenting is important * new lines are important, for example before, after and between bullet lists - * more, see :ref:`rest-common-pitfalls` * some people simply hate it diff --git a/Documentation/WritingReST/CommonPitfalls/Headers.rst b/Documentation/WritingReST/CommonPitfalls/Headers.rst deleted file mode 100644 index 7367c433..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Headers.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Headers - -===================== -Problems with headers -===================== - -If you use section titles (headers), the underline must be **at least** as long as the text. - -Though you can make the underlines longer than the text, common practice -throughout the docs is to to keep it the same length. - -.. tip:: - - If you use an IDE with good reStructuredText support, it should point - out this error correctly, for example if you use PhpStorm, enable - the `reStructuredText plugin `__. - - -Correct syntax -============== - -.. code-block:: rst - - ================ - This Is a Header - ================ - - Another Header - ============== - - - This Is Also Correct but Not Recommended - ====================================================== - - -Wrong syntax -============ - - -.. code-block:: rst - - Another Header - ------------ - - -Additional information -====================== - -* :ref:`Headlines-and-sections` -* `reStructuredText Primer: Sections `__ diff --git a/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst b/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst deleted file mode 100644 index 41975a53..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Hyperlinks.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: reST; Hyperlinks -.. highlight:: rst - -=================== -Problems with links -=================== - -There are several ways to write links, here we assume you are -using external links with the following syntax. For more information -see the :ref:`references ` -at the bottom on this page. - -Correct syntax -============== - -.. code-block:: rst - - `anchor text `__ - - -Example: - -.. code-block:: rst - - `T3O `__ - -How this looks: - -`T3O `__ - - -Common mistake #1: Missing space -================================ - -Make sure there is a space between the anchor text and the -opening `<`. - - -Wrong syntax ------------- - -.. code-block:: rst - - Wrong: `T3O`__ - - Correct: `T3O `__ - - -Common mistake #2: Missing underscore (_) -========================================= - -Missing `_` or `__` at the end: - - -Wrong Syntax ------------- - -.. code-block:: rst - - Wrong: `T3O ` - - Correct: `T3O `__ - - -.. _common-pitfalls-links-more-information: - -Additional information -====================== - -* :ref:`external-links` diff --git a/Documentation/WritingReST/CommonPitfalls/Indents.rst b/Documentation/WritingReST/CommonPitfalls/Indents.rst deleted file mode 100644 index 721b0027..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Indents.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Indentation - -===================== -Problems with indents -===================== - - -Common mistake #1: Incorrect indents -==================================== - -Always indent correctly (4 spaces per level) - - -Correct syntax --------------- - -.. code-block:: rst - - .. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow - -How it looks: - -.. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow - - -Incorrect syntax ----------------- - -Here, `:width:` is indented with only 2 spaces. The image will not be -rendered at all! - -.. code-block:: rst - - .. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow - -How it looks: - - -.. image:: /Images/a4.jpg - :width: 100px - :class: with-shadow diff --git a/Documentation/WritingReST/CommonPitfalls/Index.rst b/Documentation/WritingReST/CommonPitfalls/Index.rst deleted file mode 100644 index 55590404..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Index.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Common pitfalls -.. _rest-common-pitfalls: - -=============== -Common pitfalls -=============== - -Here we describe some common mistakes. Read this section before you start -in order to avoid common errors. - -.. tip:: - - If you use an IDE with good reStructuredText support, it should point - out these errors correctly, for example if you use PhpStorm, enable - the `reStructuredText plugin `__. - - -.. toctree:: - :maxdepth: 2 - :glob: - - * diff --git a/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst b/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst deleted file mode 100644 index 9721b90c..00000000 --- a/Documentation/WritingReST/CommonPitfalls/InlineStyle.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Inline styles -.. _common-pitfalls-inline-style: - -========================== -Problems with inline style -========================== - - -If you use **bold** or *italic*, make sure there is no space between -the markup and the styled text. - - -Correct syntax --------------- - -.. code-block:: rst - - This is normal text. **This is bold text.** - -How it looks: - - -This is normal text. **This is bold text.** - - -Wrong syntax ------------- - -.. code-block:: rst - - This is normal text. ** This is bold text.** - -How it looks: - - -This is normal text. ** This is bold text.** - - -Additional information -====================== - -* `Docutils cheat-sheet for reStructuredText: Inline markup - `__ diff --git a/Documentation/WritingReST/CommonPitfalls/Lists.rst b/Documentation/WritingReST/CommonPitfalls/Lists.rst deleted file mode 100644 index 7668328c..00000000 --- a/Documentation/WritingReST/CommonPitfalls/Lists.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: reST; Lists - -=================== -Problems with lists -=================== - -If you use lists, make sure there is an empty line before and after the -list. If you use lists with sublevels, make sure there is an empty line -between the levels and the sublevel items are left-aligned with the -parent item text. - -The same applies for bullet lists and enumerated lists. - - -Correct syntax -============== - -Example 1: Bullet list -~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: rst - - this is some text - - * this is a list item - * another item - - more text - -**How it looks:** - -this is some text - -* this is a list item -* another item - -more text - - -Example 2: List with sublist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: rst - - this is some text - - * this is a list item - - * this is a sublevel list item - * another item - - this is more text - - -How it looks: - -this is some text - -* this is a list item - - * this is a sublevel list item - * another item - -this is more text - - -Wrong syntax ------------- - -.. code-block:: rst - - this is some text - * this is a list item - * another item - more text - -How it looks: - -this is some text -* this is a list item -* another item -more text - - -Additional information -====================== - -* `Docutils cheat-sheet for reStructuredText: Bullet list - `__ -* :ref:`Section on lists in this guide ` -* `Docutils cheat-sheet for reStructuredText: Enumerated lists - `__ diff --git a/Documentation/WritingReST/Index.rst b/Documentation/WritingReST/Index.rst index 3b3f3614..6b8b6f76 100644 --- a/Documentation/WritingReST/Index.rst +++ b/Documentation/WritingReST/Index.rst @@ -20,9 +20,6 @@ It is recommended to read (or at least browse through) the :ref:`writing-rest-introduction` and the general :ref:`format-rest-cgl` first. -Also read :ref:`rest-common-pitfalls` in order to avoid common -mistakes with the syntax. - You don't need to read the entire chapter, just lookup the section that is relevant for what you plan to do. @@ -48,6 +45,5 @@ http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_ Introduction BasicRestSyntax - CommonPitfalls/Index CheatSheet Reference/Index diff --git a/Documentation/WritingReST/Reference/Content/BoldItalic.rst b/Documentation/WritingReST/Reference/Content/BoldItalic.rst index 23a608ba..2676a936 100644 --- a/Documentation/WritingReST/Reference/Content/BoldItalic.rst +++ b/Documentation/WritingReST/Reference/Content/BoldItalic.rst @@ -35,14 +35,8 @@ How it looks: This is normal text. *This is italic text.* - -Possible Errors -=============== - -.. important:: - - Make sure there is no space between the markup and the styled text, - see :ref:`common-pitfalls-inline-style`. +.. hint:: + Make sure there is no space between the markup and the styled text. Additional Information diff --git a/Documentation/WritingReST/Reference/Lists/BulletLists.rst b/Documentation/WritingReST/Reference/Lists/BulletLists.rst index ad7b0e25..5c823db8 100644 --- a/Documentation/WritingReST/Reference/Lists/BulletLists.rst +++ b/Documentation/WritingReST/Reference/Lists/BulletLists.rst @@ -58,7 +58,6 @@ Example 1: List with sublist items **How it looks:** - * item 1 * item 2 is a longer text with line breaks. We can format and indent like this @@ -69,64 +68,6 @@ Example 1: List with sublist items * item 4 +.. note:: -Example 2: List with sublist and error -====================================== - -.. important:: - - This example will not work as expected, because the extra lines - for the sublist are missing. - -.. code-block:: rst - - * item 1 - * item 2 - * item 3 - * subitem 3.1 - * subitem 3.2 - * item 4 - -**How it looks:** - -* item 1 -* item 2 -* item 3 - * subitem 3.1 - * subitem 3.2 -* item 4 - - -Example 3: List with sublist and whitespace error -================================================= - -.. important:: - - Each asterix `*` has to be followed by three spaces. - If you only use one the sublist is interpreted like - a citation. - -.. code-block:: rst - - * item 1 - * item 2 - * item 3 - - * subitem 3.1 - * subitem 3.2 - - * item 4 - -**How it looks:** - -* item 1 -* item 2 -* item 3 - - * subitem 3.1 - * subitem 3.2 - -* item 4 - - -For more information on common errors, see :ref:`rest-common-pitfalls`. + Empty lines before and after the sublist are mandatory.