reStructuredText basics

reStructuredText is the default plaintext markup language used by Sphinx.

The index.rst file

There are many tutorials out there explaining the syntax of .rst files that you can try a separate time, so we will focus now on what exists in our index.rst file.

Heading 

Welcome to Sphinxy's documentation!
===================================

This is a heading containing the project name, as generated by Sphinx. In order to specify a new section, create a heading by underlining the text with any punctuation character as long as the text. Using the same character will create headings of the same level.

Table of contents tree 

.. toctree::
   :maxdepth: 2
   :caption: Contents:
  • The toctree (table of contents tree) adds structure to your docs.
  • The maxdepth parameter specifies how many levels of headers you would like Sphinx to create in its output.
  • The caption parameter gives option to provide a toctree caption, i.e. the title of the toctree; in this case “Contents”.

Creating a section

Now let’s add some more content by modifying the file index.rst. We are going to add a new section that has some more information and a picture of a sphinx.

Create a new section above the “Indices and tables” one:

The Egyptian Sphinx
-------------------

Image

And now let’s add a picture to our new section. You can use any image you like; we downloaded one from Unsplash. You can find it under images/sphinx.png. Move your preferred image in the docs/_static directory and type under your header:

.. image:: _static/sphinx.png

If you are using codespaces, you’d need to save the image locally, then upload it to the docs/_static folder on codespaces by right-clicking on the _static directly, and selecting Upload..., then select the image you’d downloaded from the file browser to upload it.

Now, from your docs/ directory, re-run make html to see your image rendered on the site.

🙌 You have now reached the 03-rst-basics part of the tutorial. If not, check-out that branch and continue from there.


Previous: Getting started with Sphinx Next: Documenting your API