Restructured Text (RST)
is a text based markup language like markdown.
In combination with Sphinx) it is used to build this documentation,
most notable for the
official Labstreaminglayer documentation
hosted on ReadTheDocs and (some time in the future) a standalone PDF doc.
You can view the source code for
Building the documentation
documentation on ReadTheDocs
is built on every commit to the
In order to avoid several commits until you get the formatting right, install
sphinx package (either with pip or conda) and build the
make html, or (if you don’t have make installed)
sphinx-build . _build.
You can avoid repeating yourself by adding links to separate pages or
paragraphs where something is explained in more depth.
There are several ways to do this
After setting a
.. _my-label: before a section, you can refer to it as
:ref:`link text <my-label>`: link text (or, without a link text
You can link to entire documents via their relative path, excluding the file
extension with the
Omitting the link text inserts the title of the document, so
:doc:`doc_syntax` produces Documentation Syntax.
LSL documentation shortcuts
Some pages are linked to quite often, so there are some shortcuts configured in
:repo:`foo` creates a link to
(of course, you can add link texts with all these commands, e.g.
:repo:`your new start page <sccn/liblsl>`).
:lslrepo:`LabRecorder` links to
:lslrelease:`LabRecorder` to an App’s release page, i.e.
You can link to anything in the liblsl docs with the commands described in
Internal links by prefixing the label / doc with
doc:`liblsl:ref/freefuncs` produces this link: LSL freestanding functions.
You can even use this to refer to pages created directly from the documentation
comments in the C++ header files, e.g.
produces this link:
When using the predefined roles (e.g. :cpp:enum), you don’t need to prefix liblsl:, e.g.
You can list the available link targets by running
python -msphinx.ext.intersphinx https://labstreaminglayer.readthedocs.io/projects/liblsl/objects.inv.