7. VSCode reStructuredText

7.1. Usage

• Make your doc files in VSCode using reStructuredText .rst files.

• Use reStructuredText formatting syntax in your docs files.

• Some important details are specified below.

• For more details, see: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

• For a compact cheat sheet, see: https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt

---

7.2. index.rst

• Edit index.rst to include introductory info at the top.

• Edit index.rst to list other project .rst file names under table of contents directives.

Tip

index.rst should at least contain the table of contents .. toctree:: directive.

---

7.3. Documentation as .rst files

• Make your doc files in VSCode using reStructuredText .rst files.

Tip

.rst files must contain a fully underlined heading to work properly

Heading
=======

Overlining and underlined a heading also works.

=======
Heading
=======

---

7.4. Images

• Images in a subfolder can be added to .rst files using the directive .. image:: images/myimage.png.

Tip

Image path issue

• It is possible to use /../docs/images/ as the path to an images folder but those images don’t display in files in github

• It is best to use images in each docs subfolder for those .rst file with images instead of trying to use one common folder for all images.

• eg. .. image:: tutorials/images/mytut.jpg in the file tutorials/mytutinfo.rst

---

7.5. Sample code

• Python code blocks can be set out like the example below using the directive .. code-block:: python.

• Python line numbers can be included using the :linenos: option.

.. code-block:: python
    :linenos:

    from microbit import *

    x = 0
    for y in range(0, 5):
        display.set_pixel(x, y, 9)

This displays as:

from microbit import *

x = 0
for y in range(0, 5):
    display.set_pixel(x, y, 9)