programmers-reference/python/index.rst is incomplete

[Garth Wells]

The generated file

    programmers-reference/python/index.rst

is incomplete. For example, it does not include

  function/index.rst

[Garth Wells (garth-wells)]

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.

[Anders Logg (logg)]

Is it the generate_modules.py script?

Does this replace generate_dolfin_python_doc.py?

--
Anders

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

[Garth Wells (garth-wells)]

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?

Garth

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

[Kristian B. Ølgaard (k.b.oelgaard)]

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

Kristian

> Garth
>
>> --
>> Anders
>>
>>
>> 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.
>>>
>>
>
> --
> You received this bug notification because you are a member of FEniCS
> Core Team, which is the registrant for FEniCS Documentation.
> https://bugs.launchpad.net/bugs/761516
>
> 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
>

[Johan Hake (johan-hake)]

On Friday April 15 2011 08:00:02 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

Would it help to rename the function directory to functions? Are there other
similare cases?

If so, we could do the same change for the C++ name too, as the python naming
tries to folow the C++ naming. But that is strictly not nessesary.

Johan

> 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.)
>
> Kristian
>
> > Garth
> >
> >> --
> >> Anders
> >>
> >> 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.
> >
> > --
> > You received this bug notification because you are a member of FEniCS
> > Core Team, which is the registrant for FEniCS Documentation.
> > https://bugs.launchpad.net/bugs/761516
> >
> > 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

[Kristian B. Ølgaard (k.b.oelgaard)]

On 15 April 2011 17:32, Johan Hake <email address hidden> wrote:
> On Friday April 15 2011 08:00:02 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
>
> Would it help to rename the function directory to functions? Are there other
> similare cases?

It doesn't matter for the docs since I changed the strategy for
extracting the docs.
However, the following is not possible:

import dolfin
c = dolfin.function.constant.Constant(1.2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'constant'

Ideally, we should change the names to allow this usage.

Same story for compilemodules.

> If so, we could do the same change for the C++ name too, as the python naming
> tries to folow the C++ naming. But that is strictly not nessesary.

I'm indifferent, but since the problem is on the Python side (and we
generate the Python interface from C++) I don't think the 'fix'
necessarily should propagate back to C++.

Kristian

> Johan
>
>> 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.)
>>
>> Kristian
>>
>> > Garth
>> >
>> >> --
>> >> Anders
>> >>
>> >> 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.
>> >
>> > --
>> > You received this bug notification because you are a member of FEniCS
>> > Core Team, which is the registrant for FEniCS Documentation.
>> > https://bugs.launchpad.net/bugs/761516
>> >
>> > 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
>
> --
> You received this bug notification because you are a member of FEniCS
> Core Team, which is the registrant for FEniCS Documentation.
> https://bugs....

[Anders Logg (logg)]

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?

--
Anders

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

[Kristian B. Ølgaard (k.b.oelgaard)]

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.

Kristian

> --
> Anders
>
>
>> 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
>> >
>>
>
> --
> You received this bug notification because you are a member of FEniCS
> Core Team, which is the registrant for FEniCS Documentation.
> https://bugs.launchpad.net/bugs/761516
>
> 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
>

[Anders Logg (logg)]

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.

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

[Kristian B. Ølgaard (k.b.oelgaard)]

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

[Anders Logg (logg)]

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.

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

[Kristian B. Ølgaard (k.b.oelgaard)]

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

[Johan Hake (johan-hake)]

On Friday April 15 2011 09:50:30 Kristian B. Ølgaard wrote:
> On 15 April 2011 17:32, Johan Hake <email address hidden> wrote:
> > On Friday April 15 2011 08:00:02 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
> >
> > Would it help to rename the function directory to functions? Are there
> > other similare cases?
>
> It doesn't matter for the docs since I changed the strategy for
> extracting the docs.
> However, the following is not possible:
>
> import dolfin
> c = dolfin.function.constant.Constant(1.2)
> Traceback (most recent call last):
> File "<stdin>", line 1, in <module>
> AttributeError: 'module' object has no attribute 'constant'
>
> Ideally, we should change the names to allow this usage.
>
> Same story for compilemodules.

I have fixed this in my branch now. Do I need to update something in the
fenics-doc too?

Johan

> > If so, we could do the same change for the C++ name too, as the python
> > naming tries to folow the C++ naming. But that is strictly not
> > nessesary.
>
> I'm indifferent, but since the problem is on the Python side (and we
> generate the Python interface from C++) I don't think the 'fix'
> necessarily should propagate back to C++.
>
> Kristian
>
> > Johan
> >
> >> 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.)
> >>
> >> Kristian
> >>
> >> > Garth
> >> >
> >> >> --
> >> >> Anders
> >> >>
> >> >> 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.
> >> >
> >> > --
> >> > You received this bug notification because you are a member of FEniCS
> >> > Core Team, which is the registrant for FEniCS Documentation.
> >> > https://bugs.launchpad.net/bugs/761516
> >> >
> >> > Title:
> >> > programmers-reference/python/index.rst is incomplete
> >> >
> >> > Status in FEniCS Documentation:
> >> > C...

[Kristian B. Ølgaard (k.b.oelgaard)]

On 18 April 2011 21:02, Johan Hake <email address hidden> wrote:
> On Friday April 15 2011 09:50:30 Kristian B. Ølgaard wrote:
>> On 15 April 2011 17:32, Johan Hake <email address hidden> wrote:
>> > On Friday April 15 2011 08:00:02 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
>> >
>> > Would it help to rename the function directory to functions? Are there
>> > other similare cases?
>>
>> It doesn't matter for the docs since I changed the strategy for
>> extracting the docs.
>> However, the following is not possible:
>>
>> import dolfin
>> c = dolfin.function.constant.Constant(1.2)
>> Traceback (most recent call last):
>>   File "<stdin>", line 1, in <module>
>> AttributeError: 'module' object has no attribute 'constant'
>>
>> Ideally, we should change the names to allow this usage.
>>
>> Same story for compilemodules.
>
> I have fixed this in my branch now. Do I need to update something in the
> fenics-doc too?

No, as long as the __all__ variable contains everything that you want
to expose it should be fine.

Kristian

> Johan
>
>> > If so, we could do the same change for the C++ name too, as the python
>> > naming tries to folow the C++ naming. But that is strictly not
>> > nessesary.
>>
>> I'm indifferent, but since the problem is on the Python side (and we
>> generate the Python interface from C++) I don't think the 'fix'
>> necessarily should propagate back to C++.
>>
>> Kristian
>>
>> > Johan
>> >
>> >> 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.)
>> >>
>> >> Kristian
>> >>
>> >> > Garth
>> >> >
>> >> >> --
>> >> >> Anders
>> >> >>
>> >> >> 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.
>> >> >
>> >> > --
>> >> > You received this bug notification because you are a member of FEniCS
>> >> >...

[Johan Hake (johan-hake)]

On Monday April 18 2011 12:14:50 Kristian B. Ølgaard wrote:
> On 18 April 2011 21:02, Johan Hake <email address hidden> wrote:
> > On Friday April 15 2011 09:50:30 Kristian B. Ølgaard wrote:
> >> On 15 April 2011 17:32, Johan Hake <email address hidden> wrote:
> >> > On Friday April 15 2011 08:00:02 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
> >> >
> >> > Would it help to rename the function directory to functions? Are there
> >> > other similare cases?
> >>
> >> It doesn't matter for the docs since I changed the strategy for
> >> extracting the docs.
> >> However, the following is not possible:
> >>
> >> import dolfin
> >> c = dolfin.function.constant.Constant(1.2)
> >> Traceback (most recent call last):
> >> File "<stdin>", line 1, in <module>
> >> AttributeError: 'module' object has no attribute 'constant'
> >>
> >> Ideally, we should change the names to allow this usage.
> >>
> >> Same story for compilemodules.
> >
> > I have fixed this in my branch now. Do I need to update something in the
> > fenics-doc too?
>
> No, as long as the __all__ variable contains everything that you want
> to expose it should be fine.

Ok.

Johan

> Kristian
>
> > Johan
> >
> >> > If so, we could do the same change for the C++ name too, as the python
> >> > naming tries to folow the C++ naming. But that is strictly not
> >> > nessesary.
> >>
> >> I'm indifferent, but since the problem is on the Python side (and we
> >> generate the Python interface from C++) I don't think the 'fix'
> >> necessarily should propagate back to C++.
> >>
> >> Kristian
> >>
> >> > Johan
> >> >
> >> >> 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.)
> >> >>
> >> >> Kristian
> >> >>
> >> >> > Garth
> >> >> >
> >> >> >> --
> >> >> >> Anders
> >> >> >>
> >> >> >> On Fri, Apr 15, 2011 at 11:49:45AM -0000, Garth Wells wrote:
> >> >> >>> I've used a script tha...

[Johan Hake (johan-hake)]

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

[Anders Logg (logg)]

On Mon, Apr 18, 2011 at 07:47:48PM -0000, Johan Hake wrote:
> 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 d...

[Kristian B. Ølgaard (k.b.oelgaard)]

On 18 April 2011 22:03, Anders Logg <email address hidden> wrote:
> On Mon, Apr 18, 2011 at 07:47:48PM -0000, Johan Hake wrote:
>> 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