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 its own heading underline character: = - ~ ^ '
Format: Header ( HTML heading tag / reStructuredText heading underline)
Page Title (<h1> / =)
|
| ----- Category (<h2> / -)
|
| ----- Subcategory (<h3> / ~)
|
| ----- Heading option (<h4> / ^)
|
| ----- Option (<h5> / ')
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 below
.. Note::
Note would go here using the format specified below
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
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.
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
Notes
Notes are used in the manual to highlight information. All the notes follow a similar format to the standard note.
Standard note
- The standard note appears in blue.
- It should be used to give complementary information.
- It uses the following format:
.. Note:: Text of the note underneath, indented. Anything indented will be part of the note box.
Example of standard note: Bibliographic records.
Version
- The version note appears in green in the manual.
- It's an admonition note renamed "Version"; use the format shown below.
- It should only be used to indicate in which version of Koha the feature you are documenting was introduced.
- The version note should only be used for features that are new from Koha version 23.11 and in later versions. It was introduced as part of the move to one manual for all Koha versions rather than one manual for each Koha version. The one manual was introduced from Koha 23.11; if you are documenting something that was introduced in a previous version, do not use a version note.
.. Admonition:: Version This feature was added in version 24.05 of Koha.
Example version note: AcquisitionsDefaultEMailAddress system preference.
Attention
- The attention note appears in orange.
- It is used to indicate something that was moved or removed in a particular Koha version.
- It works in tandem with the Version note. Make sure you cross-reference the changes by using links in your version and attention notes to point from the old place to the new, and vice versa.
- The attention note should only be used for features that were moved or removed from Koha version 23.11 and in later versions. It was introduced as part of the move to one manual for all Koha versions rather than one manual for each Koha version. The one manual was introduced from Koha 23.11; if you are documenting something that was moved or removed in a previous version, do not use an attention note.
.. Attention:: As of version 23.11 of Koha, this feature was moved to :ref:`FeatureLocation <featurelocation-label>`.
Example attention note: TrackLastPatronActivity system preference.
Tip
- The tip note appears in a light shade of teal.
- It is used to give some useful extra information.
.. Tip:: Make sure the text of the note is indented
Example tip note: Existing notices and slips.
Warning
- The warning note appears in orange.
- It is used across the manual to inform readers of something that is important (not necessarily dangerous!)
.. Warning:: Make sure the text of the note is indented
Example warning note: Editing/Deleting a library.
Important
- The important note appears in the same teal colour as the Tip note.
- It is not used very widely. Consider whether the standard note, tip or warning would be more relevant here.
.. Important:: Make sure the text of the note is indented
Example important note: Plugins.
Code blocks
It is sometimes useful to include code blocks in the manual text.
- String of code within a line of standard text
Standard text starts here, includes :code:`code text` and continues afterwards.
- Block of multiple lines of code
.. code-block:: sql Use this for SQL statements. The functions will automatically be highlighted. Make sure all the lines that should be part of the code block are indented.
You can use the same format for languages other than SQL. Specifying a language is optional.
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