Getting started with Sphinx¶

The developers of the Lino framework make intensive use of Sphinx for writing documenting about our software.

Sphinx¶: A documentation generator written and used by the Python community. See also Wikipedia
documentation tree¶: A stand-alone set of content pages that are rendered as a website or a book.
doctree¶: Abbreviation for documentation tree.

The doctree of a source repository is usually in a directory named docs in the repository’s root directory.

A doctree must contain at least two files: the conf.py file and the index.rst file. Usually it contains many more source files with the extension *.rst, usually organized into subdirectories.

conf.py¶: The configuration file of a documentation tree.

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:

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
pm prep to link to a admin command. e.g. pm prep

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

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 prose style (#1869).