From 04055beee18308ae5752cb4f3460883c0bd8e0a4 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Wed, 1 Aug 2018 16:47:00 -0700 Subject: [PATCH] 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