Contents
This is part 3 of a four-part tutorial.
Part 3: Writing in reStructuredText
Watch the video or continue reading below:
In Part 3, we’re going to focus on the markup language that is reStructuredText. We’ll cover a few basics you will need to know to write documentation including formatting, inserting images, creating hyperlinks etc. You will definitely want to keep this reference document open for a more exhaustive resource:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
In the last part, I edited the index.rst file and changed the theme of my documentation. Now, I’m going to create a new file and start to build up the documentation.
Create a new file
- In the command line, move to the source folder and run
vim newfilename.rst - This opens up a new file in vim which you can begin editing after pressing ‘I’ (or you may choose to use another text editor as I did).
Writing with reStructuredText
1. Linking to a section or page
- Create a hyperlink target: Create a hyperlink target above a section (see Section Headings below) to link to that section, or at the very top of a page to link to that page as shown above. The format is
.. _uniquename: - Create the hyperlink:
:ref:`hyperlinkedtext <uniquename>`
2. Section Headings
Sections are identified by title headings with certain markers below the title. In the example above the ‘=‘ sign was used to identify the top-level section, and ‘-‘ was used for the sub-level below it. Other symbols you can use are `, ~, *, + and so on.
It doesn’t matter what symbol you actually use first, second etc., as long as you’re consistent throughout the documentation. The hierarchy of sections is what determines how the Table of Contents will be displayed as can be seen in the image:
3. Inline formatting
- Italics: * before and after the word. E.g. *emphasis* will render emphasis
- Bold: ** before and after the word. **more emphasis** will render more emphasis
- Bullet points: * followed by a space.
Refer to this page for more examples.
4. Inserting an image
reST uses something called directives which are extension mechanisms. This document lists all the directives available:
http://docutils.sourceforge.net/docs/ref/rst/directives.html
The directive for inserting an image with a caption is figure. If you didn’t have a caption you can replace figure with image. So to insert a captioned image, I type:
.. figure:: /images/imagename.png
Image caption
This assumed your image is in a separate folder (within the source directory) named ‘images’.1 Note that the caption should be aligned directly below the ‘f’ in figure (not the start of the line) and there should be a blank line above the caption. Spacing is everything in this language.
Now you can add options to the figure directive which gives you more control over how it looks. In the example below, I reduced the image size by 50% as well.
.. figure:: /images/imagename.png
:alt: alt text goes here
:align: location of caption
:scale: 50 %
Image caption
5. Inserting an inline image
- To insert an inline image, type
|uniquename|where you want the image to appear. - Leave a space of one line and in the next line, type:
.. |uniquename| image:: imagename
:scale: 50 %
You might need to scale the image down so it fits inline.
6. Embedding a YouTube video
- To embed a YouTube video, in YouTube click on Share below the video and then select Embed.
- Copy the HTML tag with the <iframe> tag.
3. In the text file, type in .. raw:: html
paste <iframe> code here
Make sure the <iframe> code is aligned directly below the ‘r’ in raw (so three spaces from the margin).
7. Admonitions (notes, warnings, tips)
There are directives you can use to insert a box with a special note inside. The generic admonitions let you decide how to title the box like this:
.. admonition:: Your title here
Text goes here
In the same way, you can replace ‘admonition’ with warning, tip, caution, hint and other types mentioned here. You will not have to give these a title, just enter your text (aligned!) directly underneath the directive.
Adding files to the toctree
When you create new files in your documentation, these files must be added to the toctree in the index page in order to be viewed. Enter the names of the files aligned below ‘toctree’.
Toctree options
- hidden: By default a Table of Contents will appear in the home page of your docs. If you want to hide this, include a ‘hidden‘ option under the toctree directive as shown in the image above.
- caption: You can add several toctrees to group your files separately. For example, you may have different audience groups, which you can identify with the ‘caption‘ option under toctree.
- maxdepth: This refers to how many nested headings will show in the Table of Contents. A maxdepth of 2 will show one nested heading.
There are several other options listed here:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
You can see how your work looks in the browser at any time by saving your files and running make html in the folder where you installed Sphinx.
Conclusion
We covered some basics of writing and formatting in reStructuredText. The resources below will cover everything else you need. In the next and last part of this tutorial, we’re going to push our docs onto Github and get them onto ReadtheDocs.
Resources
ReStructuredText Markup Specification: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
ReStructuredText Directives:
http://docutils.sourceforge.net/docs/ref/rst/directives.html
Sphinx documentation on reST:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html