From 04055beee18308ae5752cb4f3460883c0bd8e0a4 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 16:47:00 -0700 Subject: [PATCH 01/10] Describes actual use of `include` directive with use of targets. Signed-off-by: Michael Vincerra --- .../collaboration/documentation/cross.rst | 41 ++++++++++++++++--- .../collaboration/documentation/rest.rst | 7 ++++ 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 8b4d726d..73f7275b 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -15,16 +15,18 @@ Internal cross-references An internal cross-reference is a reference to a location within the |CLOSIA| documentation. Use explicit markup labels and the ``:ref:`` role to create cross references to headings, figures, and code examples as needed. Every -file must have a label before the title identical to the file's name in order -to be able to add cross-references without having to open the file. +file must have a label before the title, which is identical to the file's +name, in order to be be cross-referenced within the entire documentation. -The labels' naming conventions are: +Labels' naming conventions: + +* Ensure the label is unique throughout the documentation * Use only full words. * Use \- to link multiple words. -* Use only as many words as necessary to ensure the label is unique. +* Use only as many words as necessary. These are some examples of proper labels: @@ -119,6 +121,33 @@ Use this template to add a hyperlink with a separated definition: .. code-block:: rst - The state of `Oregon`_ offers a wide range of recreational activities. +The state of `Oregon`_ offers a wide range of recreational activities. - .. _Oregon: http://traveloregon.com/ +The include directive +********************* + +Clear Linux documentation also uses the ``.. include::`` +directive to include a portion of another reST file. + +Use the ``.. include::` directive to show a select portion of :ref:`rest`, as shown below. + +.. code-block:: + + .. include:: rest.rst + :start-after: incl-restructured-text-overview-end: + :end-before: incl-restructured-text-overview-end: + +In this example, note that you must: + +* Create a `target` that appears directly above a header (ease of inclusion) +* Ensure that the target is unique, as explained in :ref:`target ` +* Use a `:` at the end of the value of `start-after` and `end-before`. + +Following is the actual inclusion of the rest.rst file: + +.. include:: rest.rst + :start-after: incl-restructured-text-overview: + :end-before: incl-restructured-text-overview-end: + + +.. _Oregon: http://traveloregon.com/ diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst index 3b1a81f6..3959efe5 100644 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ b/source/clear-linux/reference/collaboration/documentation/rest.rst @@ -3,6 +3,11 @@ RestructuredText guide ###################### +.. incl-restructured-text-overview: + +Overview +******** + The |CLOSIA| uses Sphinx and RestructuredText as authoring tools for its documentation. This section contains the preferred methods for using the :abbr:`ReST (RestructuredText)` markup on your documents. Please refer to the @@ -27,6 +32,8 @@ templates, or the code-block directive, for multi-lined templates. Every use case is explained, examples provided and, lastly, templates supplied. +.. incl-restructured-text-overview-end: + .. toctree:: :maxdepth: 3 From e13738c0f5fbf2d03db19f5b38726cbc6ca7ba20 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 16:54:59 -0700 Subject: [PATCH 02/10] Adds comparison of target and anchor, trad HTML usage. Signed-off-by: Michael Vincerra --- .../reference/collaboration/documentation/cross.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 73f7275b..cbdf017e 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -83,7 +83,8 @@ This creates a link to the :ref:`label-of-target` using the text of the heading. This creates a link to the :ref:`target ` using the word -'target' instead of the heading. +'target' instead of the heading. We use the term 'target' here similar to +the way'anchor' is used in HTML. .. note:: @@ -94,7 +95,7 @@ This creates a link to the :ref:`target ` using the word External References ******************* -External references or hyperlinks can be added easily with ReST. Only +External references or hyperlinks can be added easily with reST. Only hyperlinks with a separated target definition are allowed. Do not use explicit hyperlinks consisting entire URLs. For example, links From ab77c0c7a6cf915ad1b9514f1c4952fa3877c22b Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 17:05:47 -0700 Subject: [PATCH 03/10] Add missing value for code-block in example. Signed-off-by: Michael Vincerra --- .../reference/collaboration/documentation/cross.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index cbdf017e..9d86adb0 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -132,10 +132,10 @@ directive to include a portion of another reST file. Use the ``.. include::` directive to show a select portion of :ref:`rest`, as shown below. -.. code-block:: +.. code-block:: console .. include:: rest.rst - :start-after: incl-restructured-text-overview-end: + :start-after: incl-restructured-text-overview: :end-before: incl-restructured-text-overview-end: In this example, note that you must: From 32d465787a1a770872a06a6dd27f361847bf7adb Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 17:08:57 -0700 Subject: [PATCH 04/10] Adds missing tick mark at end of include directive. Signed-off-by: Michael Vincerra --- .../clear-linux/reference/collaboration/documentation/cross.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 9d86adb0..8f275f51 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -130,7 +130,7 @@ The include directive Clear Linux documentation also uses the ``.. include::`` directive to include a portion of another reST file. -Use the ``.. include::` directive to show a select portion of :ref:`rest`, as shown below. +Use the ``.. include::`` directive to show a select portion of :ref:`rest`, as shown below. .. code-block:: console From af11db092a66c73ea2f97034043bc89874ab3e02 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 17:14:22 -0700 Subject: [PATCH 05/10] Fixes legacy error, extra line break, which broke URL. Signed-off-by: Michael Vincerra --- .../clear-linux/reference/collaboration/documentation/rest.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst index 3959efe5..cbe8696e 100644 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ b/source/clear-linux/reference/collaboration/documentation/rest.rst @@ -46,5 +46,4 @@ templates supplied. contents -.. _Sphinx documentation: - http://sphinx-doc.org/contents.html +.. _Sphinx documentation: http://sphinx-doc.org/contents.html From e6ea26dd82c1bf865cb1a37f9d80f02d44a12176 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 17:20:47 -0700 Subject: [PATCH 06/10] Corrects URI, previously dead, and redirects to actual markup section. Signed-off-by: Michael Vincerra --- .../clear-linux/reference/collaboration/documentation/rest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst index cbe8696e..9bede110 100644 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ b/source/clear-linux/reference/collaboration/documentation/rest.rst @@ -46,4 +46,4 @@ templates supplied. contents -.. _Sphinx documentation: http://sphinx-doc.org/contents.html +.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/markup/index.html From 7331b6d354b38c6a2d4fa1e0684b910f5b9059dd Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 17:34:29 -0700 Subject: [PATCH 07/10] Confirms URI correct at bottom of page. Signed-off-by: Michael Vincerra --- .../reference/collaboration/documentation/cross.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 8f275f51..25d0d664 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -130,7 +130,7 @@ The include directive Clear Linux documentation also uses the ``.. include::`` directive to include a portion of another reST file. -Use the ``.. include::`` directive to show a select portion of :ref:`rest`, as shown below. +Use the ``.. include::`` directive to show a select portion of a file. .. code-block:: console @@ -144,7 +144,7 @@ In this example, note that you must: * Ensure that the target is unique, as explained in :ref:`target ` * Use a `:` at the end of the value of `start-after` and `end-before`. -Following is the actual inclusion of the rest.rst file: +Use of the ``.. inclusion::`` for :ref:`rest` is shown below. .. include:: rest.rst :start-after: incl-restructured-text-overview: From ace4f38a596eece8f4a298b15d34de4930d25220 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 2 Aug 2018 09:26:04 -0700 Subject: [PATCH 08/10] Mod attempt to resolve reference to rest.rst, line 6 --- .../clear-linux/reference/collaboration/documentation/cross.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 25d0d664..4aa9e2c7 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -146,7 +146,7 @@ In this example, note that you must: Use of the ``.. inclusion::`` for :ref:`rest` is shown below. -.. include:: rest.rst +.. include:: ./rest.rst :start-after: incl-restructured-text-overview: :end-before: incl-restructured-text-overview-end: From 4cf7a21bc4087d3e47d585dc8a6bf69b11c20e24 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 2 Aug 2018 10:36:10 -0700 Subject: [PATCH 09/10] Adds URL for 'Sphinx documentation' close to its use. Signed-off-by: Michael Vincerra --- .../reference/collaboration/documentation/cross.rst | 1 - .../reference/collaboration/documentation/rest.rst | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 4aa9e2c7..977d5d2c 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -150,5 +150,4 @@ Use of the ``.. inclusion::`` for :ref:`rest` is shown below. :start-after: incl-restructured-text-overview: :end-before: incl-restructured-text-overview-end: - .. _Oregon: http://traveloregon.com/ diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst index 9bede110..43c71097 100644 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ b/source/clear-linux/reference/collaboration/documentation/rest.rst @@ -14,6 +14,8 @@ documentation. This section contains the preferred methods for using the `Sphinx documentation`_ for the complete list of available markup and use as much markup as possible. +.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/markup/index.html + Remember: **Changing incorrect markup is easier than adding markup from scratch.** @@ -45,5 +47,3 @@ templates supplied. code contents - -.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/markup/index.html From 5b39163851c578f97fd2e8836acb3fcaeeaf2513 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 2 Aug 2018 10:38:51 -0700 Subject: [PATCH 10/10] Removes mod attempt from previous push. Signed-off-by: Michael Vincerra --- .../clear-linux/reference/collaboration/documentation/cross.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 977d5d2c..e1143fea 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -146,7 +146,7 @@ In this example, note that you must: Use of the ``.. inclusion::`` for :ref:`rest` is shown below. -.. include:: ./rest.rst +.. include:: rest.rst :start-after: incl-restructured-text-overview: :end-before: incl-restructured-text-overview-end: