ReStructuredText - Tips and Tricks

From Koha Wiki
Jump to navigation Jump to 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.

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

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.

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
Retrieved from "https://wiki.koha-community.org/w/index.php?title=ReStructuredText_-_Tips_and_Tricks&oldid=35111"