Thursday, November 27, 2014

More updates to the community docs.

Solved two tickets

Worked on #17 and #18

A Chooser is now callable. This allowed us to write the following code:

def on_create(self, ar):
    super(RefundConfirmation, self).on_create(ar)
    qs = self.pharmacy_choices(self.granting)
    if qs.count() > 0:
        self.pharmacy = qs[0]

Until now it was necessary to write:

qs = self.pharmacy_choices.get_choices(granting=self.granting)

Checkin with these changes at 11:47 because it seems to work. But the test suite is probably broken since I changed lino_welfare.modlib.aids.fixtures.demo.

Repairing the test suite was again quite some benedictine work. Checkin at 15:00.

fabfile.py imported twice

I discovered that atelier imports the fabfile.py twice, which caused duplicate entries in atelier.env.demo_databases. Current workaround is to use the new function atelier.fablib.add_demo_database() instead of appending directly to env.demo_databases. Checkin at 15:40.

Pseudo-virtual tables

And then I solved #15. This was subtle.

The welfare.aids.ConfirmationsByGranting table is a dd.VirtualTable because welfare.aids.Confirmation is an abstract model. Like any virtual table it has neither a print action nor a detail action.

But OTOH it operates on normal database objects, and their concrete model is known at runtime via the master_instance.

That’s why it was difficult to accept that double-clicking on a row did not open the corresponding detail or that you could not print a confirmation it by right-clicking on a row.

In order to have a detail and a print function, we must turn it into a “pseudo-virtual” table: We define two methods lino.core.actors.Actor.get_pk_field() and lino.core.actors.Actor.get_row_by_pk() needed by the data store to identify the selected row.

I also learned that the dd.action() decorator is allowed only on a model, it doesn’t work on a table because Lino fails to adapt the signature of the wrapped function.

Checkin at 17:12.

autodoc : to use or not to use?

After our discussion in docs/tickets/134 I continue to struggle with the question of where to use autodoc and where not.

There are two modes of documenting an API: an “overview” mode and a “reference” mode. Both are useful and necessary. “Overview mode” is prosaic and must not depend on the internal structures. “Reference mode” is what autodoc generates. But how to connect them? Which information to put to the reference and which to the overview?

One thing seems clear: the reference documentation about lino.core.actors.Actor should be generated using docstrings and autodoc. So I started to move some documentation from the manually authored page at https://www.lino-framework.org/dev/actors.html back to docstrings in the source code.

Another thing seems clear: the reference documentation of everything below lino.modlib must be written manually because (1) a same model can have different implementing classes, (2) we want to document multiple possible Lino applications in a same doctree (but there can be only one DJANGO_SETTINGS_MODULE per autodoc run).