Sphinx provides different methods to create both internal and external cross-references. Use only the following methods to increase the consistency of the documents.
An internal cross-reference is a reference to a location within the Clear Linux* OS 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, which is identical to the file’s name, in order to be be cross-referenced within the entire documentation.
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.
These are some examples of proper labels:
.. _quick-start: .. _gerrit-access: .. _building-clear-linux:
Do not use labels like these:
.. _QuickStart: .. _How to Gain Access to Gerrit: .. _building:
As an example, this is an internal reference to the beginning of the RestructuredText guide.
Observe that the :ref: role is replaced with the title’s text. Similarly, it will be replaced with the figure’s caption. If a different text is needed the :ref: role can still be used, for example:
This is an internal reference to the beginning of this section.
Use the following templates to insert internal cross references properly.
.. _label-of-target: This is a heading ----------------- This creates a link to the :ref:`label-of-target` using the text of the heading. This creates a link to the :ref:`target <label-of-target>` using the word 'target' instead of the heading.
The template renders as:
This is a heading
This creates a link to the This is a heading using the text of the heading.
This creates a link to the target using the word ‘target’ instead of the heading. We use the term ‘target’ here similar to the way’anchor’ is used in HTML.
This type of internal cross reference works across multiple files, is independent of changes in the text of the headings, and works on all Sphinx builders.
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 like this one, https://clearlinux.org/ must be avoided.
Hyperlinks with a separated target definition allow us to place the URL after label. They are easier to update and independent of the text, for example:
Gitg is a great tool to visualize a GIT tree.
Follow these guidelines when inserting hyperlinks:
- The labels for hyperlinks must be grammatically correct and unique within the file.
- Do not create labels for hyperlinks using: link, here, this, there, etc.
- Add all target definitions at the end of the file containing the hyperlinks.
Use this template to add a hyperlink with a separated definition:
The state of `Oregon`_ offers a wide range of recreational activities.
The include directive
Clear Linux OS documentation also uses the .. include:: directive to include a portion of another reST file.
Use the .. include:: directive to show a select portion of a file.
.. include:: rest.rst :start-after: incl-restructured-text-overview: :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 target
- Use a : at the end of the value of start-after and end-before.
Use of the .. inclusion:: for RestructuredText guide is shown below.
The Clear Linux* OS uses Sphinx and RestructuredText as authoring tools for its documentation. This section contains the preferred methods for using the ReST markup on your documents. Please refer to the Sphinx documentation for the complete list of available markup and use as much markup as possible.
Remember: Changing incorrect markup is easier than adding markup from scratch.
We provide templates, examples, and use scenarios to help you write and edit documents easily. Use only the templates provided to ensure your content is consistent with the rest of the documentation.
Contributions with incorrect use of markup will not be merged until the markup is fixed. If you have any questions regarding markup, send an email to our mailing list at firstname.lastname@example.org and we will gladly help.
To allow for easy copy and paste of the provided templates, they are provided using either the “``” parenthesis, for single line templates, or the code-block directive, for multi-lined templates.
Every use case is explained, examples provided and, lastly, templates supplied.