On 16 April 2011 00:12, Anders Logg <email address hidden> wrote:
> On Fri, Apr 15, 2011 at 10:16:23PM +0200, Kristian Ølgaard wrote:
>> On 15 April 2011 20:40, Anders Logg <email address hidden> wrote:
>> > On Fri, Apr 15, 2011 at 03:00:02PM -0000, Kristian B. Ølgaard wrote:
>> >> On 15 April 2011 15:17, Garth Wells <email address hidden> wrote:
>> >> > On 15/04/11 13:21, Anders Logg wrote:
>> >> >> Is it the generate_modules.py script?
>> >> >>
>> >> >
>> >> > Yes.
>> >> >
>> >> >> Does this replace generate_dolfin_python_doc.py?
>> >> >>
>> >> >
>> >> > I think so, unless
>> >> >
>> >> >  generate_dolfin_python_doc.py
>> >> >
>> >> > does something more than pulling out doc strings. Kristian?
>> >>
>> >> generate_dolfin_python_doc.py also generate files for classes and
>> >> functions and use the autoclass/autofunction directives from Sphinx.
>> >> generate_modules.py just use automodule. The result is that for
>> >> instance the dolfin.cpp module is documented in one big file and one
>> >> has to scroll a lot the find the doc of interest. Maybe there's an
>> >> easy way to fix this?
>> >>
>> >> The problem with generate_dolfin_python_doc.py and the missing
>> >> function/index.rst file is that modules like:
>> >>
>> >> dolfin.function.function
>> >>
>> >> shadows
>> >>
>> >> dolfin.function
>> >>
>> >> when importing the dolfin module.
>> >> I've been working on a fix for this, such that the documentation is
>> >> generated from the files present in the dolfin_dir and not the module
>> >> available when simply importing dolfin. (similar to what
>> >> generate_modules.py does actually.)
>> >
>> > Would it be easy to update generate_dolfin_python_doc.py so that it
>> > can generate the docs also for FFC, UFL and other packages?
>>
>> Yes, I believe it should just be a matter of passing the appropriate
>> module to the function which extracts the submodules from the ffc/ufl
>> package trees.
>> I can have a look at it.
>
> Thanks, that would be great.

What functions and classes should be documented from a module?
Only the classes which is available when doing:

from dolfin.function.function import *

which depends on what the author put in __all__ variable.
In the above  case the class MetaNoEvalOverloading will not be documented.

We can also document classes and functions which is available when doing:

import dolfin.function.function

in which case MetaNoEvalOverloading will be documented.

I vote for the second option.

Kristian

> --
> Anders
>
>
>> Kristian
>>
>> >
>> >
>> >> Kristian
>> >>
>> >> > Garth
>> >> >
>> >> >>
>> >> >>
>> >> >> On Fri, Apr 15, 2011 at 11:49:45AM -0000, Garth Wells wrote:
>> >> >>> I've used a script that I found to extract the doc automatically. Take a
>> >> >>> look at
>> >> >>>
>> >> >>>     lp:~fenics-core/fenics-doc/1.0
>> >> >>>
>> >> >>> It seems to work well.
>> >> >>>
>> >> >>
>> >> >
>> >> >
>> >> > Title:
>> >> >  programmers-reference/python/index.rst is incomplete
>> >> >
>> >> > Status in FEniCS Documentation:
>> >> >  Confirmed
>> >> >
>> >> > Bug description:
>> >> >  The generated file
>> >> >
>> >> >      programmers-reference/python/index.rst
>> >> >
>> >> >  is incomplete. For example, it does not include
>> >> >
>> >> >    function/index.rst
>> >> >
>> >>
>> >
>> >
>> > Title:
>> >  programmers-reference/python/index.rst is incomplete
>> >
>> > Status in FEniCS Documentation:
>> >  Fix Committed
>> >
>> > Bug description:
>> >  The generated file
>> >
>> >      programmers-reference/python/index.rst
>> >
>> >  is incomplete. For example, it does not include
>> >
>> >    function/index.rst
>> >
>