fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Tuesday September 7 2010 15:10:08 Kristian Ølgaard wrote:
> 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.

I would be more concerned about Foo not ending up in the dolfin namespace than 
Foo not beeing documented.

> >> 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.

Do that, I wait some hours for that strategi tough ;)

Johan

> Kristian
> 
> > Johan
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp