Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

Building the Lino docs

This page explains how to build the Lino docs, i.e. how to generate for example the html pages you are reading right now. We assume that you have read About the Lino documentation.

Theoretically it’s easy

A Lino documentation tree is static html built from a series of Sphinx source files before it is uploaded to some web server.

When your development environment is correctly installed as explained in Install your Lino developer environment, then –theoretically– it’s easy to build a Lino doctree: you just run inv bd in the root directory of its repository:

$ go books
$ pip install -r requirements.txt
$ inv bd

This will tell Sphinx to read the .rst source files and to generate .html files into the docs/.build directory.

You can now start your browser on the generated files:

$ python -m webbrowser docs/.build/html/index.html

If you get some error message, then you need to read the Troubleshooting section.

If the doctree has use_dirhtml set to True, then the navigation in your local doctree won’t work perfectly.

Introducing Sphinx

Lino makes heavy usage of Sphinx, the dominant documentation system in the Python world. Sphinx is a tool that “makes it easy to create intelligent and beautiful documentation” and that “actually makes programmers want to write documentation!” (www.sphinx-doc.org).

For example, the “source code” of the page your are reading right now is in a file docs/dev/builddocs.rst.

Read more about the markup used by Sphinx in reStructuredText. Also Configuration.

Troubleshooting

…/docs/api/xxx.yyy.foo.rst:21:failed to import Bar

This can occur when you have an earlier build of the book on your computer, then pulled a new version of some Lino repository (or made some local code changes) and then run inv bd again.

The error should disappear either if you manually remove the specified file docs/api/xxx.yyy.foo.rst. Or, most fool-proof solution, you use the inv clean command to automatically remove cached and generated files:

$ inv clean -b

[autosummary] failed to import ‘lino.modlib.users.models’

This means that autosummary (which in turn needs autodoc) has a problem to import the module lino.modlib.users.models.

Indeed you can verify that importing this module in a normal Python session will fail:

>>> import lino.modlib.users.models  
Traceback (most recent call last):
...
ImproperlyConfigured: Requested setting SITE, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

As the error message tries to explain, the module refuses to import because DJANGO_SETTINGS_MODULE is not set. That’s related to a well-known oddness of Django: you cannot simply import a module that imports django when that environment variable is not set.

Note that the docs/conf.py contains (among others) the following lines:

from lino.sphinxcontrib import configure
configure(globals(), 'lino_book.projects.min9.settings')

This calls the lino.sphinxcontrib.configure() function, which basically does exactly what we need here: it sets the DJANGO_SETTINGS_MODULE to lino_book.projects.min9.settings.

So Sphinx activates the lino_book.projects.min9 project when generating the docs.

But your message says that something went wrong during all this.

Let’s try this:

$ # cd to ~/lino/env/repositories/book/lino_book/projects/min9:
$ go min9
$ python manage.py shell

And in that Python shell you try to import the that which Sphinx was not able to import:

import lino.modlib.users.models

Now you should see a traceback, and that traceback can help you to find the actual problem.

Let’s play

Let’s play a bit:

Open the source file of this page:

$  nano docs/dev/builddocs.rst

Edit something in that file and save your changes. Then build the book again:

$ inv bd

Then hit Ctrl-R in your browser and check whether the HTML output changes as expected.

You can undo all your local changes using:

$ git checkout docs/team/builddocs.rst

Or, if you agree to contribute your changes to the Lino project, you can submit a pull request as you would do with code changes.