ReStructuredText - Tips and Tricks

From Koha Wiki

Jump to: navigation, search

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.

Contents

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

Important

Important indicators use the format:

      **Important**

  Important uses: One [TAB]

Links

Internal links

Internal links use the format

  :ref:`linked item name`

External links

External links use the format

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

Notes

Note indicators use the format

         **Note**

  Note uses: One [TAB] plus 3 additional spaces before the notation (**Note**)

System Preferences Format

  .. _prefname-label

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

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

  Default: value (no leading spaces)

  Values:

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

  -  Value2

Description:

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

    **Important**

    Important would go here using the format specified above

       **Note**

       Note would go here using the format specified above