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:
modto link to a module. e.g.
functo link to a function e.g.
classto link to a class. Example
methto link to a method. Example
Some sphinx roles defined in
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
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
This is valid not only for models but also for
model fields field:
model methods, e.g.
user roles, e.g.
other plugin classes, e.g.
Of course above works only for plugins that have been converted to prosa style (#1869).