===========================
Thursday, November 27, 2014
===========================

More updates to the community docs.

Solved two tickets
==================

Worked on :ticket:`17` and :ticket:`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
:mod:`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 :mod:`atelier` imports the :xfile:`fabfile.py`
twice, which caused duplicate entries in
:attr:`atelier.env.demo_databases`.  Current workaround is to use the
new function :func:`atelier.fablib.add_demo_database` instead of
appending directly to
:attr:`env.demo_databases <atelier.env.demo_databases>`.
Checkin at 15:40.

Pseudo-virtual tables
=====================

And then I solved :ticket:`15`. This was subtle.  

The :class:`welfare.aids.ConfirmationsByGranting` table is a
`dd.VirtualTable` because :class:`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 :class:`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
:meth:`lino.core.actors.Actor.get_pk_field` and
:meth:`lino.core.actors.Actor.get_row_by_pk` needed by the data store
to identify the selected row.

I also learned that the :func:`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 :srcref:`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
:class:`lino.core.actors.Actor` should be generated using docstrings
and autodoc.  So I started to move some documentation from the
manually authored page at :lino:`/dev/actors` back to docstrings in the
source code.

Another thing seems clear: the reference documentation of everything
below :mod:`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).