Documentation Syntax¶

Restructured Text (RST)¶

Restructured Text (Quickstart, another Quickstart) 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 this page on Github.

Building the documentation¶

The documentation on ReadTheDocs is built on every commit to the Labstreaminglayer repository. In order to avoid several commits until you get the formatting right, install the Python sphinx package (either with pip or conda) and build the documentation with make html, or (if you don’t have make installed) sphinx-build . _build.

Linking to…¶

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

External links¶

External links can be written as `<target>`_, e.g. https://www.google.com/search?q=sphinx+cheat+sheet) or with a better link text before the URL as `link text <target>`_, e.g. a timeless classic.

Internal links¶

After setting a label with .. _my-label: before a section, you can refer to it as :ref:`link text <my-label>`: link text (or, without a link text Internal links).

You can link to entire documents via their relative path, excluding the file extension with the :doc: role. 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 conf.py:

:repo:`foo` creates a link to https://github.com/foo (of course, you can add link texts with all these commands, e.g. :repo:`your new start page <sccn/liblsl>`).

:lslrepo:`LabRecorder` links to https://github.com/labstreaminglayer/App-LabRecorder and :lslrelease:`LabRecorder` to an App’s release page, i.e. https://github.com/labstreaminglayer/App-LabRecorder/releases.

Intersphinx ¶

You can link to anything in the liblsl docs with the commands described in Internal links by prefixing the label / doc with liblsl, e.g. 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. :any:`liblsl:proc_dejitter` produces this link: proc_dejitter. When using the predefined roles (e.g. :cpp:enum), you don’t need to prefix liblsl:, e.g. :cpp:enum:`lsl_processing_options_t` produces lsl_processing_options_t.

You can list the available link targets by running python -msphinx.ext.intersphinx https://labstreaminglayer.readthedocs.io/projects/liblsl/objects.inv.