Skip to content

Commit

Permalink
Docs: add short introduction to RST syntax and special links
Browse files Browse the repository at this point in the history
  • Loading branch information
tstenner committed Mar 26, 2021
1 parent a7092b0 commit 6995508
Show file tree
Hide file tree
Showing 2 changed files with 101 additions and 0 deletions.
100 changes: 100 additions & 0 deletions docs/dev/doc_syntax.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
====================
Documentation Syntax
====================

Restructured Text (RST)
=======================

Restructured Text
(`Quickstart <https://docutils.sourceforge.io/docs/user/rst/quickstart.html>`_,
`another Quickstart <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_)
is a text based markup language like markdown.
In combination with `Sphinx <https://www.sphinx-doc.org/>`_) it is used to build this documentation,
most notable for the
`official Labstreaminglayer documentation <https://labstreaminglayer.readthedocs.io/>`_
hosted on ReadTheDocs and (some time in the future) a standalone PDF doc.

You can view the source code for
`this page <https://github.com/sccn/labstreaminglayer/blob/master/docs/dev/doc_syntax.rst>`_
on Github.

Building the documentation
--------------------------

The
`documentation on ReadTheDocs <https://labstreaminglayer.readthedocs.io/>`_
is built on every commit to the
:repo:`Labstreaminglayer repository <labstreaminglayer/labstreaminglayer>`.
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

:samp:`make html`, or (if you don't have :command:`make` installed)
:samp:`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 :samp:`\`<{target}>\`_`,
e.g. `<https://www.google.com/search?q=sphinx+cheat+sheet>`_) or with a better
link text before the URL as :samp:`\`{link text} <{target}>\`_`, e.g.
`a timeless classic <https://www.youtube.com/watch?v=oHg5SJYRHA0>`_.


.. _my-label:

Internal links
~~~~~~~~~~~~~~

After setting a
`label <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref>`_
with :samp:`.. _{my-label}:` before a section, you can refer to it as
:samp:`:ref:`{link text} <{my-label}>``: :ref:`link text <my-label>` (or, without a link text
:ref:`my-label`).

You can link to entire documents via their *relative* path, excluding the file
extension with the
`:doc: <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc>`_ role.
Omitting the link text inserts the title of the document, so
:samp:`:doc:`doc_syntax`` produces :doc:`doc_syntax`.


LSL documentation shortcuts
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some pages are linked to quite often, so there are some shortcuts configured in :file:`conf.py`:

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

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

`Intersphinx`_
~~~~~~~~~~~~~~

.. _Intersphinx: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

You can link to anything in the :doc:`liblsl docs <liblsl:index>` with the commands described in
:ref:`my-label` by prefixing the label / doc with ``liblsl``, e.g.
:samp:`doc:`liblsl:ref/freefuncs`` produces this link: doc:`liblsl:ref/freefuncs`.

You can even use this to refer to pages created directly from the documentation
comments in the C++ header files, e.g. :samp:`:any:`liblsl:proc_dejitter``
produces this link: :any:`liblsl:proc_dejitter`.

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

1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ LabStreamingLayer's Documentation
:maxdepth: 1
:caption: Developer's Guide

dev/doc_syntax
dev/dev_guide
dev/app_dev
dev/build_android
Expand Down

0 comments on commit 6995508

Please sign in to comment.