Welcome | Get started | Dive into Lino | Contribute | Topics | Reference | More

Getting started with Sphinx

Sphinx

The documentation system used by the developers of the Lino framework.

Read the reStructuredText Primer to get an introduction to the syntax.

If you have an example of what you want to get in the web version of the book, then look at the source code of that page via the View source code link at the bottom of the page.

Referencing to something

When you remain within one doctree (i.e. link to another page of the same doctree) and you want to refer to a whole page, use the :doc: role.

When you want an intersphinx link (e.g. a link from your blog to the book), use the :ref: role.

To link to a Python object that is part of Lino, use the following roles:

Some sphinx roles defined in lino.sphinxcontrib.base:

Generated API docs versus prosa

Lino websites about some Python package contain two main menu entries "API" and "Reference". The difference is that API docs are automatically generated using autodoc, which extracts the docstrings from source code while the Reference section is written in prose style.

Plugins generally cannot be documented using autodoc because they are extensible and because Django would refuse to import two variants of a same plugin within a same Sphinx build process. So prose style is preferred for documenting plugins.

prose style

When documentation about source code is written by a human, not generated using autodoc.

prose style documentation has the advantage of being more readable since the author can decide about the documents' structure. The challenge with prosa style is that it needs extra care when some code changes.

When referring to Django application code, there is an additional thing to know: many plugins are documented using prosa style instead of having their docs generated with autodoc. The plugin itself (the __init__.py file) is documented using autodoc. e.g. lino.modlib.users. Models and everything below top-level is documented in a /specs page which uses the currentmodule directive to tell Sphinx that it is going to document Python code objects. That's why you can refer e.g. to a model by saying e.g. lino.modlib.users.User (with autodoc you would have to write lino.modlib.users.models.User).

This is valid not only for models but also for

Of course above works only for plugins that have been converted to prose style (#1869).