__init__.py files not included in documentation

[kohr-h]

The docstrings in the __init__.py files do not end up in the Sphinx documentation. I think they should, since they are a good place to put an introduction to the subpackage contents.

In contrast, I'd argue that one only writes a minimal docstring at the top of a module so that one does not have to scroll all the way down to see the code.

[adler-j]

Added in above commit, is that OK?

[kohr-h]

The result looks correct, but what is it that makes __init__.py to be included?

[kohr-h]

Oh wait, now the private call() and _apply() are listed, too, see e.g. in the LinCombOperator.

[adler-j]

The result looks correct, but what is it that makes __init__.py to be included?

The lines .. automodule:: odl.operator in the odl.operator style files

Oh wait, now the private call() and _apply() are listed, too, see e.g. in the LinCombOperator.

This has been the case for quite a while, its regulated here.

Thats because users tend to put some doc in there.

[kohr-h]

Alright. We should then probably add a line like

Do not use this method directly. Call ``operator(x)`` to evaluate the operator.

to the _call() methods of our operators, and similarly for _apply().

[adler-j]

The best would be if the documentation of _call and _apply was somehow moved into the documentation of __call__ and the _call/_apply doc simply changed to

Do not use this method directly. Call ``operator(x)`` to evaluate the operator.

Maybe this could be done programmatically with some post processing script?

[kohr-h]

Interesting. I'll make a new issue so we can close this.

[adler-j]

New issue on _call and _apply is #48.

[kohr-h]

Yeah, forgot to link back...