__init__ file and autoclass_content

[coke...@googlemail.com]

Dear all,

I've been using Sphinx for a week now to document a python/c++ project
and I should say that I'm quite happy about it and will pursue in this
direction.

However, I've noticed that none of the __init__ functions appear in
the documentation pages when using the *automodule* option.

Reading the sphinx documentation I figured out that I could use the
*autoclass_content* option in the conf.py file. So, I set it to 'both'
so as to get the docstring of the class as well as the docstring of
the __init__ constructor. However, the result is not correct, or at
least it is not what I expected: instead of the class docstring
followed by the __init__'s docstring, I get the class docstring
twice.


Any thoughts or help on this issue ?
cheers,
Thomas Cokelaer

PS: I was using the version 0.5.1

[Georg Brandl]

coke...@googlemail.com schrieb:

Hmm, I've tried to reproduce this, but I cannot find a problem with 0.5.1
and an example class. How does your class look like? How do you use
autoclass/automodule?

Georg

[Thomas Cokelaer]

Hi Georg,

Here below is an example of a class that causes the problem.

The HTML output below the class name (and base name) is

%MatPlotLib implementation
%
%test
%
%MatPlotLib implementation
%
%test


class mplotlib(plotter):
"""
MatPlotLib implementation

test
"""
linestyles = ('-', '--', ':', '.')
pointstyles = ('o', '^', 'x', '+', 's', 'v', '>', '<')
colors = ('g', 'r', 'y', 'b', 'k', 'm', 'c')

def __init__(self):
""" Initialize matplotlib

test2"""

import matplotlib
import pylab
self.pylab = pylab

def plot(self, plotable, title, groups=[], *args, **kargs):
"""
Plot a plotable with title
groups : list of group (int) to plot
"""
....


thanks
Thomas

--
Dr Thomas Cokelaer
UMR DAP
Avenue d'Agropolis - TA A-96/02 (Bat 2)
34398 Montpellier Cedex 5
Tel: 04 67 71 58 00 (ask number 5471)

[Thomas Cokelaer]

Hi Georg,

For completeness, the automodule directive is used as follows inside an
reST file:

.. automodule:: <full name of the module>
:members:
:undoc-members:
:inherited-members:
:show-inheritance:
:synopsis: Plot functions

Except for the problem of having the init docstring replaced by the main
docstring of the class, the remaining HTML output is as expected, as far
as I know. I dig a little bit inside the autodoc extension and the
docstring of the __init__ method is read but somehow at some point, it is
replaced by the class's docstring.

cheers
Thomas

[Georg Brandl]

Thomas Cokelaer schrieb:

> Hi Georg,
>
> For completeness, the automodule directive is used as follows inside an
> reST file:
>
> .. automodule:: <full name of the module>
> :members:
> :undoc-members:
> :inherited-members:
> :show-inheritance:
> :synopsis: Plot functions
>
> Except for the problem of having the init docstring replaced by the main
> docstring of the class, the remaining HTML output is as expected, as far
> as I know. I dig a little bit inside the autodoc extension and the
> docstring of the __init__ method is read but somehow at some point, it is
> replaced by the class's docstring.

Hmm, I've tried to reproduce it with the examples you gave me, but still no
luck. Is your Sphinx project publicly available somewhere?

Georg

[Thomas Cokelaer]

Hi Georg,

Thanks for looking at this issue. Unfortunately, the documentation is not
yet public and the project is not small and trivial to install. I will
look at the __init__ file again later. I know that the option
autoclass_content works and this is already something good to know.

This may be related to my configuration file. I will try with a simple one
and see if it works. I let you know anyway once I succeed to parse the
init.

cheers
Thomas

[Georg Brandl]

Thomas Cokelaer schrieb:
> Hi Georg,
>

> Thanks for looking at this issue. Unfortunately, the documentation is not
> yet public and the project is not small and trivial to install. I will
> look at the __init__ file again later. I know that the option
> autoclass_content works and this is already something good to know.
>
> This may be related to my configuration file. I will try with a simple one
> and see if it works. I let you know anyway once I succeed to parse the
> init.

Thank you! I'm sorry I couldn't be of more help, so I'm glad if you're able
to do some detective work on it.

In any case, autodoc has been almost completely rewritten in the trunk; so
it might work out of the box there.

Georg

[Thomas Cokelaer]

Hi Georg,

I've downloaded the last Sphinx version from the webpage and still got the
same issue with the init__ docstring not being parsed properly.

I've investigated a litlle bit further and looked at the autodoc.py
extension. The __init__ docstring is read as expected. So, the
configuration is set correctly. Then, the __init__ docstring is appended
to the class docstring.

However, in the process_doc function (~line 405), in the loop "for
docstringlines in docstrings", the class docstring is returned twice.

Indeed, the "docstrings" contains the following list:

docstrings = [["class dostring"],["init docstring"]]

However, the problem occurs in the call to "self.env.app.emit", where the
variable docstringlines is replaced by docstrings[0]

so the loop : "for line in docstringlines" always loop over the class
docstring.

Any thoughts on how to cope with ? I tried to flatten the docstrings but
this does not solve the issue.

cheers
Thomas

[Georg Brandl]

Thomas Cokelaer schrieb:
> Hi Georg,
>

> I've downloaded the last Sphinx version from the webpage and still got the
> same issue with the init__ docstring not being parsed properly.
>
> I've investigated a litlle bit further and looked at the autodoc.py
> extension. The __init__ docstring is read as expected. So, the
> configuration is set correctly. Then, the __init__ docstring is appended
> to the class docstring.
>
> However, in the process_doc function (~line 405), in the loop "for
> docstringlines in docstrings", the class docstring is returned twice.
>
> Indeed, the "docstrings" contains the following list:
>
> docstrings = [["class dostring"],["init docstring"]]
>
> However, the problem occurs in the call to "self.env.app.emit", where the
> variable docstringlines is replaced by docstrings[0]

Hmm. Do you have a handler attached to the autodoc-process-docstring event
that does this? Normally, there shouldn't be any change in the docstringlines
from this call.

Georg