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. Examplelino.core.model.Model
meth
to link to a method. Examplelino.core.model.Model.get_data_elem()
Some sphinx roles defined in lino.sphinxcontrib.base
:
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).