Editing Pages

Warning

This page is under construction.

To contribute or participate contact support@boost-lab.net

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 and Figures

See also Figures and images.

Images and figures 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.png

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

reST supports an image directive (ref), used as follows:

.. image:: /images/common/comingsoon.png
        :height: 100px
        :width: 200 px
        :scale: 50 %
        :alt: alternate text
        :align: right

Figure 139 The coming soon image

Figures have a text to describe the image otherwise they have the same syntax as images as follows:

.. figure:: /images/common/comingsoon.png
             :height: 100px
             :width: 200 px
             :scale: 50 %
             :alt: alternate text
             :align: right

             The coming soon image

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.

Videos

Videos are either referenced from the internet (e.g. for youtube) or stored in the _static and referenced from the pages.

To reference a local video the following should be used, where the path is the relative path from the page to the video:

.. raw:: html

        <video width="560" height="315" controls src="../../../_static/videos/architectures01.mp4">

To refence a youtube video the following should be used.

.. raw:: html

        <iframe width="560" height="315" src="https://www.youtube.com/embed/ncMlaE48HlA" frameborder="0" allowfullscreen></iframe>

Tip

The complete iframe text can be copied from the youtube page for the video.

The result looks as follows:

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.

One-off Hyperlinks

See also Keywords.

External Hyperlinks

It is recommended that external hyperlinks are stored in the Keywords for ease of maintenance.

If a one-off link is needed, no special markup is needed as the parser will recognise a hyperlink.

If replacemenet text is needed then the following should be used:

Link text

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

Internal Hyperlinks

The only internal hyperlink recommented is :ref:. The others are included here for completeness.

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

: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>`.
  

: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`

: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
_static	videos		This folder contains any videos that are held in the documentation
_themes			This contains Sphinx theme files
images			This the images that form this documentation
pages			This folder contains rst files that form this documentation

Authors

These can be added using the sectionauthor and optionally keywords. e.g.

.. sectionauthor:: |Judith Crockford|
.. sectionauthor:: `Judith Crockford <mailto:judith.crockford@airbus.com?subject=STEPlib Documentation>`_

Either of these return:

Section author: Judith Crockford

Sphinx Themes

Sphinx Themes are either imported in the conf.py or referenced from 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.

Watermark

The watermark is provided by the sphinxmark extension.

The watermark can be text or an image; controlled by settings in the conf.py

Section author: Judith Crockford (AP243)