ReStructuredText - Tips and Tricks

The newer Koha manuals are using reStructuredText. This page will be used to gather information about how certain things are handled in our manual an help to get people started working with reStructuredText.

Headings

At the moment we use 5 levels of headings in the manual. In HTML this will translate from <h1>-<h5>.

A <h4> heading looks something like this:

Rebuild Index
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Every level uses it's own heading underline character: = - ~ ^ '

Format: Header ( HTML heading tag / reStructuredText heading underline)
    
Page Title (<h1> / =)
           |
           | ----- Category (<h2> / -)
                            |
                            | ----- Subcategory (<h3> / ~)
                                                |
                                                | ----- Heading option (<h4> / ^)
                                                                       |
                                                                       | ----- Option (<h5> / ')

Ordered lists

Ordered or numbered lists can be generated using #.

Example:

  #. first item
  #. second item

Will be turned into:

  1. first item
  2. second item

Warnings

Warnings indicators use the format:

.. Warning ::

   Make sure the text of the note is indented

Links

Internal links

Add labels before headings or areas of text that you want to link to, for example:

  .. _my-unique-heading-label:

  My unique heading
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To link internally use this format:

  :ref:`linked item name <name-of-label>`

Notes:

• Labels must be unique across the manual, not just the current file.

External links

Use this format for external links:

  `link description <http://www.something.com>`_.

If no link description is required use the URL without any special formatting, for example:

  Visit https://dangitgit.com/ for tips on fixing Git mistakes.

Notes

Note indicators use the format

.. Note::

   Text of the note underneath, indented

Images

In the images.rst file, under the right heading, add the path to the image as well as a descriptive alt text for the image

.. |filename| image:: images/path/filename.png
               :alt: Text describing the image

Headings in the images.rst file correspond to the directories in the /images directory.

In the chapter, you can simply enter the alias for the image

text text text text text 
text text text text text 

|filename|

text text text text text 
text text text text text 

Comments

Comments are bits of text that will not appear in the actual manual. They will only be visible in the source files.

Comments start with ..

.. This is a comment

System Preferences Format

  .. _prefname-label

  SystemPreferenceName
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  Asks: \_\_\_ units (underscores MUST be escaped in ReStructuredText syntax -- no leading spaces)

  Values:

  -  Value1 (no leading spaces before the hyphen(-) -- two(2) spaces between hyphen and value text)

  -  Value2

  Default: value (no leading spaces)

  Description:

  -  Syspref description goes here (no leading spaces before the hyphen(-) -- two(2) spaces between hyphen and the description text)

  .. Warning ::

     Warnings would go here using the format specified above

  .. Note ::

     Note would go here using the format specified above