by Kristina D.C. Hoeppner
This is a list in progress as I work on the user manual. There are a number of things for which I created conventions. I want to keep them in a central space so that others have access to them and that I can refer to them as well. ;-)
The list is not in any particular order.
Most screenshots are added with the figure directive:
Example of including a screenshot
Note
If you want to include an image inline with the text and don’t want to or can’t use the regular figure, you should create a substitution and place it into the shortcuts.rstext file.
note: for anything that should receive a bit more attention
Note
Notes can be placed directly within a bulleted list. As usual, an empty line before and after the note must be placed and the admonition must be indented by 3 spaces.
warning: for anything that needs to be done with caution
Warning
Try not to put everything into an admonition because then the truly important information is lost.
seealso: for references to other documents if they need special attention. References to other documents can also be included in the text inline.
See also
The Sphinx user documentation is a great place to deepend your knowledge and understanding of using rST with Sphinx. If you have any questions, you can also check out the Sphinx discussion group.
todo: for keeping a running ToDo list
Todo
Add any additional info for documentation writers and translators when necessary.
Each section that is related to a navigation menu item should have the path listed, e.g. Content → Files. It is best if you copy the arrow to get the correct one.
Buttons such as Save or Copy page and also portfolio sections such as Content, Porfolio etc. are highlighted as emphasized text (with a single *).
Little buttons can be included in the text like ,
. They are added through a substitution. All replacements are kept in the file shortcuts.rstext which is included in each file in which a substitution is used by placing “.. include:: /shortcuts.rstext” in the first line of the file. Substitutions are referenced in the text as “*Edit* button |edit|” for example pointing out what the action is that you do with them. Translators should not edit the substitution “|edit|” itself, but only change “*Edit* button” taking care to include the * again without placing any spaces between the * and the text to ensure that the word appears highlighted.
An index entry should be created for each section.
New features receive an index entry as well in the form “single: New in Mahara 1.x, [the functionality that is new]”.
Long sections should be broken up into several pages to make the editing more manageable instead of having everything on one very long page.
reStructuredText does not have a set hierarchy of heading levels. They depend on the individual files. However, to be consistent, the following convention exists:
- Heading 1, e.g. 1.: ===============
- Heading 2, e.g. 1.1.: —————
- Heading 3, e.g. 1.1.1.: ~~~~~~~~~~~~~~~
- Heading 4, e.g. 1.1.1.1.: ^^^^^^^^^^^^^^^
Headings below h4 should be avoided.
The index page does not have headings besides the main heading. That prevents the table of contents and the other sections that have headings to be the main chapters of the manual. Keep index page headings to just bold with **.
Index entries are used to jump to relevant information quickly. Entries can be created right above a heading or also inline. Inline has the advantage that you are taken exactly where you want to go.
Note
If you want to mention the names of the main translators of the user manual for your language, you can add a sentence right after “The Mahara user manual is written by Mahara community members.” That paragraph appears before the table of contents. There is no equivalent sentence in the English manual because it is not a translation.