Getting started with Sphinx

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 Show Source link at the bottom of each page.

Referencing to something

When you remain within one doctree (i.e. link to another page of the book) 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:

• mod to link to a module. e.g. lino.core.actions

• func to link to a function e.g. lino.utils.join_words()

• class to link to a class. Example lino.core.model.Model

• meth to link to a method. Example lino.core.model.Model.get_data_elem()

Some sphinx roles defined in lino.sphinxcontrib.base:

• demo to link to a fixture name. e.g. demo

• prep to link to a admin command. e.g. prep

Generated API docs versus prosa

The Lino book contains "API docs" and "Specifications". These are two very different beasts. The main difference is that API docs are automatically generated using autodoc which extracts the docstrings from source code while the Specifications are written in prosa 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 prosa style is preferred for documenting plugins.

prosa style

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

Prosa 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

• choicelists lino.modlib.users.UserTypes

• model fields field: lino.modlib.users.User.username

• model methods, e.g. lino.modlib.users.User.get_full_name()

• actions, e.g. lino.modlib.users.ChangePassword

• user roles, e.g. lino.modlib.users.Helper

• other plugin classes, e.g. lino.modlib.users.UserType

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