fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 7 September 2010 23:07, Johan Hake <johan.hake@xxxxxxxxx> wrote:
> [snip]
>
>> >> My point is, there's no telling where the cpp.Mesh class was
>> >> originally defined. Everything from la to mesh to fem is dumped in the
>> >> cpp.py module.
>> >
>> > Ok, but don't you just need a way to associate the classes to different
>> > modules? I thought this was what you used the doxygen output to.
>>
>> Yes, this is the plan. I thought I could use doxygen to tell me that
>> the class Mesh is defined in dolfin/mesh/Mesh.h, and then associate
>> the dolfin.cpp.Mesh class with the dolfin/mesh directory to generate
>> prog-ref/python/mesh/Mesh.rst.
>
> Ok, the module way to do it might just yield what module you are in. But you
> should be able to check wether an instance in the module dict is a class, if
> so generate a .rst file for it.

Certainly.

>> But come to think of it, the potential renaming will screw this up arrrrgh.
>
> Should not be a problem if you go for my approach ;)

I know. :)

>> If we instead
>>
>> > use the module representation we should be able to do this association
>> > directly with just the dolfin tree as the assosiated types should reside
>> > in:
>> >
>> >  dolfin.submodule.__dict__
>>
>> This has some potential, we just need to be careful what the
>> submodules import.
>
> Definately!
>
> We either define a __all__ variable or just fill the module with some:
>
>  from cpp.py import Mesh, ...
>
> and skip the __all__ variable.
>
>> The big drawback as I see it is that if someone
>> adds a class to say dolfin/mesh/Foo.h, we'll need to manually import
>> it in dolfin/mesh/__init__.py.
>
> Well, that is what we already do, but we add it to dolfin/__init__.py, which
> we agree is messy.

All this is doable and relatively easy to manage if you stay on top of
it, my concern is just that if a class is added to C++ DOLFIN its
Python counterpart will end up in cpp.py and if it is not imported in
any submodule (or dolfin/__init__.py itself) a user can still reach it
by: dolfin.cpp.Foo, but there will be no documentation generated in
the programmer's reference.

>> In the long run, I think that the doxygen approach will yield the most
>> stable result, but we'll most likely have to look in the *.i files for
>> %rename.
>
> I might disagree with you. However you know the rst generation much better
> than me, so you just do what you think is best, and cost less wrt maintanance.

There's nothing to it once we have the Python module, we just let
Sphinx autodoc handle it i.e., for any given class Bar in module foo
we dump the following in the file dolfin/foo/Bar.rst

.. currentmodule:: dolfin.foo

.. autoclass:: Bar
  :members:
  :+ other options:

Let's sleep on it and see what we can dream up.

Kristian

> Johan
>