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

Introduction to config directories

Lino has a concept of configuration directories that are a bit like Django’s templates directories.

Side note: Code snippets (lines starting with >>>) in this document get tested as part of our development workflow. The following initialization snippet tells you which demo project is being used in this document.

>>> import os
>>> os.environ['LINO_CACHE_ROOT'] = '' # disable for this doctest
>>> from lino import startup
>>> startup('lino_book.projects.confdirs.settings')
>>> from lino.api.doctest import *

Concepts

The settings.SITE.confdirs attribute holds a singleton instance of lino.utils.config.ConfigDirCache, which is the registry for config directories. It is initialized once at startup.

config

A directory named config that is collected at startup into a list of directories to be searched when looking for configuration files.

plugin configuration directory

A config directory in the source directory of a plugin.

site configuration directory

A config directory in the project directory of a Lino site.

local configuration directory

A site configuration directory that contains locally customized template files.

Site config dirs are searched before plugin config dirs.

>>> settings.SITE.confdirs  
<lino.utils.config.ConfigDirCache object at ...>
>>> for cd in settings.SITE.confdirs.config_dirs:
...     print(cd.name, cd.writeable)  
/.../lino_book/projects/confdirs/config True
/.../lino_xl/lib/contacts/config False
/.../lino/modlib/users/config False
/.../lino/modlib/printing/config False
/.../lino/modlib/extjs/config False
/.../lino/modlib/bootstrap3/config False
/.../lino/modlib/jinja/config False
/.../lino/config False

The local configuration directory

All configuration directories are read-only (maintained by the application developer) except one: the local configuration directory.

>>> rt.find_config_file('admin_main.html')  
'.../lino_book/projects/confdirs/config/admin_main.html'

How to make local print templates editable by end users

Some end users want to be able to configure themselves certain templates.

First step : make a local copy of the relevant templates:

$ go mysite
$ cp -a env/lib/python3.6/site-packages/lino_xl/lib/trading/config .

Second step: make the local config directory accessible to the end user via SSH or WebDAV or any other method.

Typical workflow

Here is a typical workflow for a local template optimization.

  • Some user wants some change in a printed output.

  • The template manager needs to know a database object that serves as example.

  • Figure out how to clear the cache and rebuild the printable document without creating useless database content such as new excerpts.

  • Find out which file is being used as template. Look at the lino.log if you have no idea where to start.

  • Create a backup copy of the template file.

  • Make some change, save the template file, rebuild the printable.

  • When you are satisfied, remove the backup file.

Implementation details

The lino_book.projects.cosi1 demo project has a site config dir. This is our demo case of a local config dir. When the cosi1 tests were run on travis (i.e. LINO_CACHE_ROOT is set), Lino forgot to add the cosi1 site’s config dir to its list of config dirs. Another problem was that these “non-local site config dirs” (for which cosi1 on travis is the only example) must come before the plugin config dirs. See config.