Types of documentation¶

Technical documentation includes topic guides, reference documentation, the changelogs and others.

reference documentation¶

A section of documentation pages that are intermediate between developer guide and user guide.

Reference documentation is not only for developers, it can be a valuable help for support providers and motivated key users.

Reference docs contain class descriptions for database models and data tables.

Reference docs are not translated like the user guide.

local help pages¶

A doctree that is automatically generated by a Lino site. These pages are what opens when you click the help button (?).

See also About local help pages.

site documentation¶

Another name for local help pages.

end-user documentation¶

Documentation for end users of a given Lino site. Written in the language(s) requested by the site operator.

developer documentation¶

Documentation written for software developers and motivated site experts. Only in English. May include tested source code snippets and part of the test suite.

The developer documentation for lino, lino_xl and getlino is in the Lino Developer Guide, the doctree of the book repository. The book repository contains Python source code for a package lino_book. This package is not published on PyPI because it meant to be cloned by developers who install it from the editable source code using pip install -e.

The book repository also includes the developer documentation for a set of “privileged” applications (Lino Noi, Lino Tera, Lino Avanti, …) because it’s difficult to explain Lino without examples, and because real applications are the best example.

Otherwise every newer typical Lino application has its own doctree. Lino Amici is an example. The doctree of amici can refer to the book via Intersphinx.

We also maintain the atelier and etgen packages, which come “before” Lino in the dependency chain. These packages have their own doctree, which doesn’t “know” about Lino. But the book “knows” about them and wants to refer to them.

Most conf.py files use atelier.interproject.configure() to configure intersphinx dependencies, and rstgen.sphinxconf.configure() to install default Sphinx settings that are common to all doctrees.

Python dependencies :

book -> xl -> lino
book -> noi -> lino
lino -> etgen -> atelier
amici -> xl -> lino

Doctree intersphinx dependencies:

amici -> book -> atelier

Documenting Django models.py modules has the particular challenge that they cannot be imported without a DJANGO_SETTINGS_MODULE, and this setting may not change within one Sphinx doctree. That’s why the doctree of the book uses lino_book.projects.max as its DJANGO_SETTINGS_MODULE during build.