Editing Pages

This documentation details how to edit reStructured Text pages. This content has been apropriately extracted from the offical Sphinx documentation available here.

reStructuredText in general

Recommended Applications

Sphinx utilises a set of Python scripts to easily compile documentation from ASCII text. This ASCII text is saved to files in ReStructuredText. It is important to use a suitable text editor; word processing applications such as Word are rich text editors which may apply formatting to the text which is not suitable to be used for ReStructuredText.

Below is a list of popular editors for creating and editing RST files:

• Notepad++

  • This editor only allows for editing RST files and not compiling

• Eclipse - ReST plugin

  • This editor can create Sphinx projects, edit and auto format RST files and compile Sphinx projects.

Common Mistakes

Common Mistakes will be populated over time, however according to the documentation, the following are common mistakes:

There are some problems one commonly runs into while authoring reST documents:

• Separation of inline markup: As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a backslash-escaped space to get around that.
• No nested inline markup

The reStructuredText for these pages

A Basic Structure

Below is a very basic template which can be used to begin adding content to the document.:

.. Comment

Page Title
##########

.. toctree::
:maxdepth: 2

Contents Item 1
Contents Item 2

Chapter Title
*************

=======
Heading
=======

-----------
Sub-Heading
-----------

^^^^^^^^^^^^^^^
Sub-sub-Heading
^^^^^^^^^^^^^^^

* :ref:`genindex`
* :ref:`search`

The following items have significance: * maxdepth refers to the depth to which the contents are populated * Contents Items refer to the rst file name e.g. index for index.rst * genindex will create an index of pages * search implements search functionality

Special Characters

To be investigated

Text, Paragraphs and Lists

Text is arranged in paragraphs

It is possible to have bulleted lists like this:

• Bullet 1

• Bullet 2

  • Sub-Bullet 1
  • Sub-Bullet 2

• Bullet 3

It is also possible to have enumerated lists like this:

1. Point 1
2. Point 2
3. Point 3

In ReStructuredText this paragraph is written:

Text is arranged in paragraphs

It is possible to have bulleted lists like this:

* Bullet 1
* Bullet 2
   * Sub-Bullet 1
   * Sub-Bullet 2
* Bullet 3

It is also possible to have enumerated lists like this:

#. Point 1
#. Point 2
#. Point 3

In ReStructuredText this paragraph is written::

   [This code]

Admonitions

Admonitions are specially marked “topics” that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as on offset block in a document, sometimes outlined or shaded, with a tile matching the admonition type.

Attention

Attention

This is an attention admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for an Attention Admonition:

.. attention::
   This is an attention admonition. It can contain any other type of text e.g. lists, or tables

   So long as they are indented accordingly

Caution

Caution

This is a caution admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for a Caution Admonition:

.. caution::
   This is a caution admonition. It can contain any other type of text e.g. lists, or tables

   So long as they are indented accordingly

Danger

Danger

This is a danger admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for an Danger Admonition:

.. danger::
   This is a danger admonition. It can contain any other type of text e.g. lists, or tables

   So long as they are indented accordingly

Error

Error

This is an error admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for an Error Admonition:

.. error::
   This is an error admonition. It can contain any other type of text e.g. lists, or tables

   So long as they are indented accordingly

Hint

Hint

This is a hint admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for a Hint Admonition:

.. hint::
   This is a hint admonition. It can contain any other type of text e.g. lists, or tables

   So long as they are indented accordingly

Important

Important

This is an important admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for an Important Admonition:

.. important::
   This is an important admonition. It can contain any other type of text e.g. lists, or tables

   So long as they are indented accordingly

Note

Note

This is a note admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for a Note Admonition:

.. note::
This is a note admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Tip

Tip

This is a tip admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for a Tip Admonition:

.. tip::
This is a tip admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Warning

Warning

This is a warning admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Below is the ReStructuredText required for a Warning Admonition:

.. warning::
This is a warning admonition. It can contain any other type of text e.g. lists, or tables

So long as they are indented accordingly

Images

Images can placed anywhere in the rst page. The can be between paragraphs, in tables or in lists. It is best practice that all images reside in the images folder and it can have any name and file extension (that is valid with internet browsers).

To avoid overwriting images from other pages it is recommended that the images are called xxx01.png where xxx is the id of the page e.g. editpages01.jpg

The following is quoted from the Sphinx Documentation guide (here):

reST supports an image directive (ref), used like so:

.. image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right

The following options are recognised:

alt

alt:text

Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users

height

height:length

The desired height of the image. Used to reserve space or scale the image horizontally. As with “height” above, when the “scale” option is also specified, they are combined. For example, a height o 200px and a scale of 50 is equivalent to a height of 100px with no scale

width

width: length or percentage of the current line width

The width of the image. Used to reserve space or scale the image horizontally. As with “height” above, when the “scale” option is also specified, they are combined.

scale

scale: integer percentage (the “%” symbol is optional)

The uniform scaling factor of the image. The default is “100%”, i.e. no scaling

If no “height” or “width” options are specified, the Python Imaging Library (PIL) may be used to determine them, if it is installed and the image file is available.

align

align: “top”, “middle”, “bottom”, “left”, “center”, or “right”

The alignment of the image, equivalent to the HTML <img> tag’s deprecated “align” attribute or the corresponding “vertical-align” and “text-align” CSS properties.

target

target: text (URI or reference name)

Makes the image into a hyperlink reference (“clickable”). The option argument may be a URI (relative or absolute), or a reference name with underscore suffix.

When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.

Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the _static directory for HTML output.)

Interpretation of image size options (width and height) is as follows: if the size has no unit or the unit is pixels, the given size will only be respected for output channels that support pixels. Other units (like pt for points) will be used for HTML and LaTeX output (the latter replaces pt by bp as this is the TeX unit such that 72bp=1in).

Sphinx extends the standard docutils behaviour by allowing an asterisk for the extension:

.. image:: gnu.*

Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Supported image types and choosing priority are defined at Available builders.

Note that image file names should not contain spaces.

Tables

There are two forms of tables that are supported in reStructuredText:

Grid Tables

To create a grid table, you have to “paint” the cell grid yourself.

Header Column 1 (header rows optional)	Header Column 2	Header Column 3	Header Column 4
Body Row 1, Column 1	Body Row 1, Column 2	Body Row 1, Column 3	Body Row 1, Column 4
Body Row 2, Column 1	Body Row 2, Column 2	Body Row 2, Column 3	Body Row 2, Column 4

+------------------------+----------------------+----------------------+----------------------+
| Header Column 1        | Header Column 2      | Header Column 3      | Header Column 4      |
| (header rows optional) |                      |                      |                      |
+========================+======================+======================+======================+
| Body Row 1, Column 1   | Body Row 1, Column 2 | Body Row 1, Column 3 | Body Row 1, Column 4 |
+------------------------+----------------------+----------------------+----------------------+
| Body Row 2, Column 1   | Body Row 2, Column 2 | Body Row 2, Column 3 | Body Row 2, Column 4 |
+------------------------+----------------------+----------------------+----------------------+

Simple Tables

Simple tables are much easier to create, however they must contain more than one row, and the first column cannot contain multiple lines. (Auto formating in Eclipse does not work for these types of tables)

Header Column 1	Header Column 2	Header Column 3
Row 1, Column 1	Row 1, Column 2	Row 1, Column 3
Row 2, Column 1	Row 2, Column 2	Row 2, Column 3

===============   ===============   ===============
Header Column 1   Header Column 2   Header Column 3
===============   ===============   ===============
Row 1, Column 1   Row 1, Column 2   Row 1, Column 3
Row 2, Column 1   Row 2, Column 2   Row 2, Column 3
===============   ===============   ===============

Code Fragments

Code Fragments are written into ReStructuredText bt ending a paragraph with the marker ::. The code must then be indented and be separated from other paragraphs by blank lines. The following example was extracted from the Sphinx Documentation:

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except that indentation is removed.

   It can span multiple lines.

This is a normal text paragraph

Expanding Sections

This section is an expanding section, to create an expanding section add

.. rst-class:: expand

before any section header.

Keywords and Automatic hyperlinks

There are several options that could be investigated:

Option 1 - Manually include all hyperlinks (Manual Method)

The first option is that automatic hyperlinks are not investigated and each hyperlink is input manually by the content creator as detailed in One-off Hyperlinks

Pros	Cons
Simple to implement	Difficult to update multiple hyperlink locations
Does not require any separate files	Requires more thought from the content creator

Conclusion: Only recommended for one off Hyperlinks

Option 2 - Manually include references to hyperlinks in a file (Semi-Automatic Method)

The second option is to predefine a list of hyperlinks in a seperate .rst file and then replace string’s of interest with the contents of that file using the reStructuredText ‘replace’ functionality.

To utilise the replace functionality, the separate .rst file must be called using the ‘include’ command by every document. The ‘replace’ functionality then searches and replaces text that has been contained within two | characters.

Pros	Cons
Quick to call hyperlinks	Difficult to update Hyperlink text
Simple to update hyperlink locations	Requires manually selecting characters in the documents

Conclusion: This would be useful functionality when you only wish to repeat a hyperlink occasionally in the documentation.

Option 3 - Run a parser to perform the manual requirements of Option 2 (Automatic Method)

A script could be implemented that is either executed prior to the build or during build to insert the two | characters required for option 2.

Option 3a - Running a preparser prior to the build (Preferred)

In this scenario the following steps would be followed:

• Two keywords .rst files are created.
  • autoKeywords.rst - This would be a list of the keywords and associated hyperlinks that are to be automatically replaced.
  • manualKeywords.rst - This would be a list of the keywords and associated hyperlinks that are NOT to be automatically replaced, but called as in option 2.
• A preparser would read an earlier version of autoKeywords.rst and accordingly remove the appropriate surrounding | characters in the documentation .rst files.
• The preparser would then read the latest version of autoKeywords.rst and surround occurrence of these keywords in the documentation .rst files with | characters.
• The documentation .rst files are then saved and so long as the autoKeywords.rst and manualKeywords.rst files are included in all documentation, then the documentation can be compiled.

Pros	Cons
Quick to call hyperlinks	The preparser changes the content of the documentation .rst files
Simple to update hyperlink locations	Requires a preparser to be created
Allows for automated hyperlink creation	A backup of autoKeywords is always required, so that changes to existing hyperlinks can be made

Conclusion: This method would allow for the ultimate flexibility with limited drawbacks.

Option 3b - Running a modified documentation builder

In this scenario the following steps would be followed:

1. Two keywords .rst files are created. autoKeywords.rst - This would be a list of the keywords and associated hyperlinks that are to be automatically replaced. manualKeywords.rst - This would be a list of the keywords and associated hyperlinks that are NOT to be automatically replaced, but called as in option 2.
2. A modified builder for the project is used for the build and the | characters are included during the build process

Pros	Cons
Quick to call hyperlinks	Requires custom Sphinx builders to be created (Difficult)
Simple to update hyperlink locations	Moving away from using a standardised documentation tool
Allows for automated hyperlink creation
Does not change the content of the documentation .rst files

Conclusion: This method would produce the easiest system for updating documentation. However by moving away from generic Sphinx builders, we lose the ability to compile in the virtually infinite list of Sphinx formats and move away from using a standardised documentation tool.

Option 4 - Create a preparser that replaces keywords with hyperlink strings (Automatic Method)

A preparser could be created that negates the use of reStructuredText’s Find and Replace functionality and instead manually replaces all of the keywords in the documentation .rst files with the appropriate ReST hyperlink code.

Pros	Cons
Quick to call hyperlinks	The preparser changes the content of the documentation .rst files
Simple to update hyperlink locations	Requires a preparser to be created
Allows for automated hyperlink creation	Makes it difficult to revert the changes or make updates to keywords

Conclusion: This method would be simple to implement however makes it extremely difficult to make changes to Keywords

Conclusion

The preferred method going forward would be Option 3a. Where a preparser implements the reStructuredText Find and Replace | characters through the documentation.

This method uses the most core functionality available in ReStructuredText. Although this would perform edits to the documentation .rst files, any changes could easily be reversed.

One-off Hyperlinks

External Hyperlinks

As quoted from the Sphynx documentation: If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text. e.g.:

Link text

`Link text <http://example.com/>`_

Internal Hyperlinks

This is a brief summary of the internal hyperlink functionality detailed in the Sphynx Documentation on Cross Referencing:

:any:

This convenience role tries to do its best to find a valid target for its reference text

• First, it tries standard cross-reference targets that would be referenced by doc, ref or option.

If none or multiple targets are found, a warning will be emitted. In the case of multiple targets, you can change “any” to a specific role.

Reference is located :any:`my-reference-label`

:ref:

To support cross-referencing to arbitrary locations in any document, the strandard reST labels are used. For this to wrok label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels:

• If you place a label directly before a section title:

  .. _my-reference-label:
  
  Section to cross-reference
  --------------------------
  
  This is the text of the section
  
  It refers to the section itself, see :ref:`my-reference-label`.
  

  This would then generate a link to the section, with the link title being “Section to cross-reference”. This works just as well when section and reference are in different source files.

• Automatic labels also work with figures, given:

  .. _my-figure:
  
  .. figure:: The Figure
  
     Figure caption
  
     Reference to the figure with the caption, :ref:`my-figure`.
  

• Labels that aren’t placed before a section title can still be referenced to, but you must give the link an explicit title:

  .. _my-reference-label:
  
  This is the text of the seciton
  
  The refence is located :ref:`here <my-reference-label>`.
  

:doc:

Linking to a specified document; provide the relative path and filename without the extension (the extension is added during compile)

Consider that we are editing FlyingCircus.rst in the following directory structure:

• [Source Directory]

  • index.rst

  • titles

    • movies

      • FlyingCircus.rst
      • HolyGrail.rst

    • sketches

  • resources

    • People.rst

The other three documents can be referenced accordingly:

Reference to the Holy Grail, :doc:`HolyGrail`

Reference to index, :doc:`/index` or :doc:`../../index`

Reference to People, :doc:`/resources/People` or :doc:`../../resources/People`

If no explicit link text is given:

A list of the :doc:`Monty Python members </resources/People>`

Note

The given filename is usually relative to the directory the current source file is contained in, but if it is absoulute (starting with /), it is taken as relative to the top source directory.

:download:

This role allows you to link to files within your source tree that are not reST documents, but are files that can be downloaded.

When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only). All downloadable files are put into the _downloads subdirectory of the output directory; duplicate filenames are handled.

An example:

See :download:`this example script <../example.py>`.

Note

The given filename is usually relative to the directory the current source file is contained in, but if it is absoulute (starting with /), it is taken as relative to the top source directory.

The example.py file will be copied to the output directory, and a suitable link generated to it.

If you wish to not show unavailable download links, e.g. when exporting to PDF, you should wrap whole paragraphs that have this role:

.. only:: builder_html

   See :download:`this example script <../example.py>`.

:numref:

Link to the specified figures, tables, code-blocks and sections; the standard reST labels are used. When you use this role, it will insert a reference to the figure with link text by its figure number like “Fig. 1.1”.

If an explicit link text is given e.g.

:numref:`Image of Sphinx (Fig. %s) <my-figure>`

The links caption will be the tile of the reference.

:option:

A command-line option to an executable program. This generates a link to a option directive, if it exists.

Directory Structure and other files

Where to place files

There is a basic file structure that should be adhered to when adding pages to the documentation. The source folder should consist of the files ‘index.rst’ and ‘conf.py’ with the folders ‘_static’, ‘_templates’, and ‘objects’. These should not be changed.

Root Folder	Sub Folder	Sub Folder 2	Content
_static			This contains fixed attached files, any files inserted here are not processed by the compiler, only copied into the build folder
_themes			This contains Sphinx theme files
objects			This the editable objects that form this documentation
objects	backend		This folder contains external backend files
objects	documents		This folder contains .rst files of text for each page
objects	images		This folder contains any images that are held in the documentation
source	videos		This folder contains any videos that are held in the documentation

Authors

To be considered using Glossary terms perhaps?

Sphinx Themes

Sphinx Themes are stored in the folder:

\source\_themes

Within these a themes’ CSS and JavaScript functions can be created and integrated.

Sphinx Builds are constructed using the conf.py file within the source, editing this determines how HTML, PDF, ePub etc builds are created.