.. comment all inline tags to start with _help_edit_ .. index:: How to; Edit pages .. _help_edit_top: Editing Pages ############# .. include:: /pages/common/pageunderconstruction.txt :start-line: 3 This documentation details how to edit reStructured Text pages. This content has been apropriately extracted from the offical Sphinx documentation `available here `_. .. contents:: Contents: :local: :depth: 1 :backlinks: top reStructuredText in general *************************** .. contents:: Contents: :local: :depth: 1 :backlinks: top ======================== 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 ************************************ .. contents:: Contents: :local: :depth: 1 :backlinks: top ================= 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: #. Point 1 #. Point 2 #. 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 =========== .. contents:: Admonitions: :local: :depth: 1 :backlinks: top 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 :ref:`help_rules_img`. 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 `_): .. image:: /images/common/comingsoon.png :height: 100px :width: 200 px :scale: 50 % :alt: alternate text :align: right 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:: /images/common/comingsoon.png :height: 100px :width: 200 px :scale: 50 % :alt: alternate text :align: right 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 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