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.
The Lino Book is static html which is visible at different places, e.g. at http://www.lino-framework.org, at lino.readthedocs.io or (when you've built it) locally on your computer.
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
book
repository:
$ 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
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 u'lino_book.projects.noi1e.tests.test_notify'¶
This means that autosummary (which
in turn needs autodoc) has a
problem to import the module
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
because 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
following lines:
from lino.sphinxcontrib import configure
configure(globals(), 'lino_book.projects.max.settings.doctests')
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.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:
import lino_book.projects.noi1e.tests.test_notify
Now you should see the traceback that is getting swallowed by autodoc.
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 Primer. Also The build configuration file.
Let's play¶
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
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.