20141223 (Tuesday, 23 December 2014)

I worked even more at the developer’s documentation. This time especially the API.

Note how this decision might seem insane at first: I have at least four customer projects waiting with a concrete, well-known list of tasks to be done, and customers ready to pay for it (mj, gx, df, üü). Lino Così is almost ready for market, and two hosters are waiting to get the last 5% done. And still I decide to start yet another project which promises to take at last several more workdays and for which there is nobody who asked me to do it, and nobody will ever pay me for doing it. I do this because there is no reason to panic. The only way to get out of this deadlock is to find other developers who love Lino. And in 2014 I learned that the primary reason for other developers to turn away after some hours of interest is some stupid problem they encounter with the documentation or the “internal beauty” of the code. So I said to myself that my customers need to wait anyway, and that the whole Lino project makes no sense if I remain the only developer. That’s why decided to tidy up documentation during the next workdays. Here is what I did:

• My concrete aim was to get the docs to build without warnings (i.e. with the env.tolerate_sphinx_warnings = True in Lino’s fabfile.py). That’s done now.

• Lots of content restructuring.

• Also some internal changes to make the code more pythonic.

• In atelier, renamed fab md (“make docs”) to fab bd. Added blog/2013 to the list of excluded documents (which are not visible on the web page, but their .rst source files remain in the repo.

• Wrote and posted another patch for Sphinx: autodoc warns without giving the source file name

• The whole docs/tickets tree is no longer included into the build.