Tuesday, March 5, 2019

Hamza and I were glad to have the production upgrade done and the release notes published, but there is more to do: the developer documentation and the test suite (Reference) needs to be updated.

But before doing so, I must do another step of reorganizing these specs. The specs for welcht were still in the book repository. Now I moved them to the welcht repository. As a consequence the mathieu demo project moved to lino_welfare.projects.mathieu (because it is no longer needed in the book, and it is now needed for testing the specs in welcht).

I am currently still trying to get the following references to work:

Some of above links don’t yet work. Read on for the explanaation.

We need to decide for every doctree who is the “maintainer” or “publisher”. The maintainer of a doctree is the person who runs inv pd, which syncs his locally generated html output files to /home/xxx/public_html/yyy_zzz on The Lino framework where xxx is the username, yyy is the project’s nickname and zzz is the name of the doctree within the project.

There are two doctrees in welcht :

  • docs (technical docs in English)

  • frdocs (the French docs)

Hamza is already the maintainer for frdocs (we configured Apache to serve /home/hamza/public_html/welcht_frdocs to fr.welfare.lino-framework.org), but I am (currently) still the maintainer of the technical welcht docs. We will make Hamza the maintainer of these as well as soon as I explained all this to him.

This morning I (not Hamza) updated the frdocs for welcht and added some new reference targets.

Theoretically I cannot refer to these targets from my blog until Hamza has built and published these frdocs. Which disturbed me at least for above references. This is because atelier.sphinxcontrib.interproject uses the “official” objects.inv file on The Lino framework which is still the old version. To get them work nevertheless, I added a new ATELIER_USE_LOCAL_BUILDS to tell atelier that it should use my local copies. But that didn’t work as at first. I had to re-read the docs about intersphinx_mapping and discover that either it has changed or I didn’t understand it when wrote the code in atelier.sphinxcontrib.interproject. Fixed the bug. Now I can build my blog, and it generates the correct references. The only thing is that if you click on them you get a “Your file was not found” because (this is not my job) Hamza must now pull my changes and build and publish these docs before they get official.

As a summary, I had some work with fixing intersphinx problems. And that’s normal because we are using them now even more than before.

Note also that we might avoid the question of “Who is the maintainer?” if we would use readthedocs for all our doctrees.