Writing reStructuredText

Funkwhale’s documentation is written using a standard markup language called reStructuredText. It is similar to Markdown and other web-based markup languages, but is better suited to technical documentation due to its standardized nature. A full syntax breakdown can be found here, but the following should be enough to get you started on writing docs for Funkwhale.

Headings

Headings are useful for splitting up text into relevant subsections. With Sphinx, major headers and direct subheaders are rendered as navigation links on Index pages, which makes them ideal for sharing specific information quickly.

Headers are written like so:

Header 1 //Equivalent to <h1>
========

Header 2 //Equivalent to <h2>
--------

Header 3 //Equivalent to <h3>
^^^^^^^^

Note

Underlines should be at least as long as the words they underline

Links

Links can be rendered in several different ways depending on where they link to:

`external link <https://example-url/>`_

:doc:`link to document <../relative/doc/path>`

Inline references can also be generated using the following syntax:

:ref:`This links to the text <link-ref>`

.. _link-ref:

The text you want to jump to

Lists

Bullet point lists are usually written using dashes like so:

- Item 1
- Item 2
- Item 3

Blocks

Blocks can be used to easily and concisely present information to a reader and are particularly useful when demonstrating technical steps. Blocks in reStructuredText can be written as follows:

.. code-block:: shell

   write terminal commands here

.. code-block:: python

   write Python code here

.. code-block:: text

   write text here

Other syntax highlighting is available. See the spec for full details.

Note

Content within code blocks should be indented by three spaces. You can end the code block by removing the indent.

Notes and Warnings

Notes are great for presenting important information to users and providing additional context. Warnings can be very useful if a step you’re writing about could potentially have adverse consequences.

.. note::

   Your note goes here

.. warning::

   Your warning goes here!

Note

Content within notes and warnings should be indented by three spaces. You can end the block by removing the indent.