20141204 (Thursday, 04 December 2014)

Documentation on readthedocs is obsolete

I noticed that there is a very old version of the Lino docs at readthedocs.org, which is of course a bad thing because people start to follow tutorials and invest their time just to discover that they have been reading obsolete documentation.

So I started to try to solve it. The build on RTD fails because it does not find the objects.inv files of other projects (atelier, djangosite, north…) . So I started to register these as well.

But already the build for atelier shows two warnings:

/var/build/user_builds/atelier/checkouts/latest/docs/index.rst:24: WARNING: toctree contains reference to nonexisting document u'api/atelier'
WARNING: html_static_path entry u'/var/build/user_builds/atelier/checkouts/latest/docs/.static' does not exist

Yes, that’s because I run fab api before running Sphinx in order to generate the pages below docs/api. It seems that RTD has no possibility to configure a shell command to run before running Sphinx. And they are right. My method of manually issuing fab api is a bit old-fashioned. I should somehow automatize this.

This made me discover sphinx.ext.autosummary, introduced by firegurafiku on stackoverflow.

Converted the atelier api docs to this new system. Seems cool! Added a condition to the fab api command so that it does nothing when there is no docs/api directory.

Released version 0.0.4 of atelier (simply fab release) because I believed that RTD cannot work on a development version.

Added a requirements.txt file and checked the Use virtualenv option in :menuselection` Admin –> Advanced Settings`.

Next problem was:

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/atelier/envs/latest/local/lib/python2.7/site-packages/atelier-0.0.4-py2.7.egg/atelier/sphinxconf/base.py", line 257, in command_parse
    signode += addnodes.literal_strong(sig, sig)
AttributeError: 'module' object has no attribute 'literal_strong'

This is because I use a node literal_strong which has been added in Sphinx 1.3. That version of Sphinx is not yet released and thus not available on RTF. So I use now literal_emphasis instead of literal_strong.

Got it working at least for atelier . That’s enough for this time.

Using milestones in Trac

I am learning how to organize my work using Trac. This is an important step for Lino. Started a new document /community/team (which meanwhile moved to /team/trac).

For ÖSHZ Eupen we have one big project which we call “Sozialsekretariat”. The project has already seen quite some releases, demonstrations, discussions…

And yesterday we had a phone session where Gerd forwarded some problem reported by their users. These problems are not part of the “Sozialsekretariat” project but should get solved ASAP. That is, with the next upgrade.

This example shows us that we must create one “milestone” in trac for every upgrade. Which means that I must rename the current milestone “Sozialsekretariat 1.0” to something like “gx-2014-12”.

Naming milestones is another discussion topic. We cannot use release numbers since every upgrade needs a milestone and we have more than one upgrades before we do a release.

Another topic of discussion is: theroetically we should create one trac ticket for every reported problem. But in this case I created a “grouped” ticket: #23.

Tickets

Gerd reported some more quick problems:

  • Ausdruck AMK : Unterzeichner steht hinter den Anlagen
  • Ausdruck AMK : “für den Zeitraum <NIX> Anrecht auf Übernahme folgende…”
  • NB: auch im Ausdruck EiEi fehlt die Periode (z.B. Auszug 974)

Which I registered as three tickets:

Since I considered that table with orphaned controllables should be lino.OrphanedControllables and not e.g. system.OrphanedControllables, I stumbled again over docs/tickets/134. And made a rather heavy step (considering that there are more urgent things to do): lino.dd no longer imports anything from lino.mixins. Josef Kejzlar and Johannes Meixner and will like it. And I agree that they were right at least for this part of dd.

The body templates of aids confirmations use a context variable {{when}} which contains the covered period. But this context variable was not defined.