Thursday, April 29, 2021¶
Improving the documentation about Lino¶
I continued my dive into the documentation framework.
My next avalanche of changes is rather in the docs themselves. That’s a good sign: the documentation framework starts to meet my expectations, I can start to care about the content.
We need a common standard for structuring the docs and reduce redundant explanations.
I moved the “User Guide” section from book/docs to cg/docs where they are
called “Using Lino”. That was needed because
cg is for
non-technical end-user documentation that will be translated.
EDIT: the next morning I continued this move, see Friday, April 30, 2021.
I have a feeling that the title of the
book doctree will change from “The
Lino Book” to “Lino developer docs”, and the
cg will rather get a title like
“The Lino Book”.
Isn’t it a pity that we cannot use the demo projects of the book for running doctests in other repositories as well? Answer after some trying: no. For example in users : Managing users it seems to me that it would make sense to add tested code snippets.
The fundamental difference between
cg is their audience. book
is meant for developers. We do not want to maintain translations for it.
About intersphinx dependencies. The book (quite often) refers to something that is explained in the cg. But at the moment we still have references in the other direction as well (cg referring to book). This is not good because it can cause a deadlock. The end-user docs should indeed really be implementation-agnostic. But Lino should have Help buttons that open links to the technical reference.
Testing whether references work:
Release to Jane¶
Sharif and I did an upgrade on Jane.