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 -.
A 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 ( / =)
 |
 | ----- Category ( / -)
 |
 | ----- Subcategory ( / ~)
 |
 | ----- Heading option ( / ^)
 |
 | ----- Option ( / ')
== 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
== Permissions Format ==
.. _permission-parent-name-label:
Parent Permission Name (permission\_code)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Top-level or parent permission (e.g. "circulate") description goes here. 
.. _permission-child-label:
Child permission (child\_permission\_code)
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Child permission (e.g. "circulate_remaining_permissions") description goes here.
== Bullet points ==
Bullet point lists use the hyphen, followed by two spaces.
- Item
- Item
- Item
If the item is longer than one line, the text must be indented to be aligned with the text of the first line.
- This item is only one line
- This item has a lot of text
 and the text continues on 
 several lines
For sub-bullets, align the bullet to the text of the parent bullet.
- Item
- Item
 - Sub item
 - Sub-sub item
 - Sub-sub item
 - Sub item
- Item
== 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 first introduced. Backported versions should not be mentioned.
* 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 first introduced 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.
=== Danger ===
* The danger note appears in red.
* It is only used if there is something that could be actually dangerous (for instance putting a password somewhere in plain text).
.. Danger::
 Make sure the text of the note is indented
Example danger note: Adding a vendor.
=== 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.
For multiline blocks, it is also possible to use a double colon `::`. The rest of the text must be indented.
 ::
 
 Block of
 multiple lines
A double colon will be transformed into a single colon and followed by preformatted text.
 Bla bla bla. For example::
 
 The double colon after 'example' will be transformed
 into a single colon, and this text will be preformatted.
* Sample text (code formatting without code highlighting)
 .. code-block:: text
 
 Use this for sample text or default text that
 needs to be differentiated from the regular
 manual 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
Category:Documentation