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

{: .tip } 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.

{: .hint } 🙌 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](./2-getting-started-with-sphinx.md){: .btn .float-left} [Next: Documenting your API](./4-documenting-your-api.md){: .btn .btn-purple .float-right}