On Monday April 18 2011 11:32:29 Kristian B. Ølgaard wrote:
> On 18 April 2011 18:55, Anders Logg <email address hidden> wrote:
> > On Sun, Apr 17, 2011 at 09:27:44AM +0200, Kristian Ølgaard wrote:
> >> 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.
> > 
> > Why would we want to document MetaNoEvalOverloading? Sounds to me like
> > a good example of something that should not be in the manual.
> 
> Not saying that it should, but what if it was some base class which
> was only used to derive classes from, and only derived classes were in
> __all__. Then a user reading the manual would not know about the base
> class. You could argue, of course, that this is not important in the
> documentation of the API and that a developer (implementing derived
> classes) would look in the source file anyway.
> Furthermore, many modules do not contain the __all__ variable and we
> would have to make sure to keep them updated.

I think we should require that python modules include this variables. It were 
only two modules not including a __all__ variable. I have fixed these in my 
branch now.

Johan


> I tried to implement the approach I was advocating, but it turned out
> to be rather complex (I will only begin to explain the problems if
> someone really wants to know). So from an implementation point of
> view, I have changed my mind and would now prefer to document only
> what is in the __all__ variable. :)
> 
> Kristian
> 
> > --
> > Anders
> > 
> >> Kristian
> >> 
> >> >> 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