Building the Lino Book¶
This page explains how to build the Lino Book, i.e. how to generate the html pages you are reading right now.
Theoretically it's easy¶
When your development environment is correctly installed as explained
in Installation, then --theoretically-- it's easy to build the Lino
Book: you just run
inv bd in the root directory of your
$ go book $ inv bd
This will tell Sphinx to read the .rst source files and to generate
.html files into the
docs/.build directory. Voilà.
If you get some error message, then you need to read the Troubleshooting section. Otherwise you can now start your browser on the generated files:
$ firefox docs/.build/html/index.html
Or jump directly to your local copy of this page:
$ firefox docs/.build/html/team/builddocs.html
.../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
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 u'lino_book.projects.noi1e.tests.test_notify'¶
Indeed you can verify that importing this module in a normal Python session will fail:
>>> import lino_book.projects.noi1e.tests.test_notify 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
DJANGO_SETTINGS_MODULE is not set. That's related
to an oddness of Django (one of its well-known and widely accepted
oddnesses): 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
from lino.sphinxcontrib import configure configure(globals(), 'lino_book.projects.max.settings.doctests')
So Sphinx uses the
lino_book.projects.max project when
generating the docs.
But your message says that something went wrong during all this.
Let's try this:
$ # cd to ~/projects/book/lino_book/projects/max: $ go max $ python manage.py shell
And in that Python shell you try to import the module which Sphinx was not able to import:
Now you should see the traceback that is getting swallowed by autodoc.
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.
Let's play a bit:
Open the source file of this page:
$ nano docs/team/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