[sphinx-dev] "Unexpected indentation." with no explainable cause

[Erik Tollerud]

I've been using sphinx w/ autodoc to generate documentation for a
project (http://packages.python.org/Astropysics/), But I keep getting
the following warning in one of my modules:

/home/erik/src/astropysics/astropysics/models/__init__.py:docstring of
astropysics.models:9: (ERROR/3) Unexpected indentation.
/home/erik/src/astropysics/astropysics/models/__init__.py:docstring of
astropysics.models:9: (ERROR/3) Unexpected indentation.

I cannot for the life of me figure out what this error is caused by,
other than that it's isolated to a particular sub-module inside the
models module (models.core, to be exact). Is there a way to get
sphinx to print out the docstring that is causing this error? Or at
the very least give me something more than just a filename that anyway
doesn't seem to be correct(given that it seems to be refrerencing the
automodule call to another module)?

--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To post to this group, send email to sphin...@googlegroups.com.
To unsubscribe from this group, send email to sphinx-dev+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.

[Michael Rule]

I am also having that problem in some files. My temporary solution,
since I do not have time to track it down, is to delete the offending
documentation from the source and insert it into the compiled HTML
manually after the fact. Not a very good solution.

[Howard Butler]

I am getting it too, though on older versions of sphinx + docutils, it doesn't happen, and I think it is because something has gotten more strict. I have also tried adjusting the offending docstring multiple ways, and I can't figure out *what* exactly it doesn't like about the indentation.

I suspect this might be a false positive or some sort of regression, but I haven't done the homework to confirm.

Howard

[Guenter Milde]

On 2010-04-19, Howard Butler wrote:
> I am getting it too, though on older versions of sphinx + docutils, it
> doesn't happen, and I think it is because something has gotten more
> strict. I have also tried adjusting the offending docstring multiple
> ways, and I can't figure out *what* exactly it doesn't like about the
> indentation.

You might try to copy the docstring (without the quotes!) to a text
file and run Docutil's rst2html.py on it to get more info.
(As many Sphinx directives and roles are unknown to "pure"
rst, you might have to eliminate some "false positives".)

Günter

[Max Battcher]

Guenter Milde wrote:
> On 2010-04-19, Howard Butler wrote:
>> I am getting it too, though on older versions of sphinx + docutils, it
>> doesn't happen, and I think it is because something has gotten more
>> strict. I have also tried adjusting the offending docstring multiple
>> ways, and I can't figure out *what* exactly it doesn't like about the
>> indentation.
>
> You might try to copy the docstring (without the quotes!) to a text
> file and run Docutil's rst2html.py on it to get more info.
> (As many Sphinx directives and roles are unknown to "pure"
> rst, you might have to eliminate some "false positives".)

Your best bet rather than just copy and paste is something along the
lines of:

$ python
>>> from docutils.core import publish_parts
>>> publish_parts(myfunc.__doc__)

This should make it a bit more obvious when you encounter what I would
guess to be one of the most likely non-obvious causes of formatting
errors from docstrings, which is docstrings in a form like:

def myfunc():
"""This is the first line.
More lines here.
Another line.
So forth."""

If you check myfunc.__doc__, you'll see that the first line has no
indentation and all of the remaining lines have indentation:

This is the first line.
More lines here.
Another line.
So forth.

I think that generally your best bet is to prefer docstrings like so:

def myfunc():
"""
This is the first line.
More lines here.
Another line.
So forth.
"""

(I think the second docstring just looks better/cleaner as well, but I
realize that some people prefer the "jagged" original.)

--
--Max Battcher--
http://worldmaker.net

[Guenter Milde]

On 2010-04-19, Max Battcher wrote:
> Guenter Milde wrote:
>> On 2010-04-19, Howard Butler wrote:
>>> I am getting it too, though on older versions of sphinx + docutils, it
>>> doesn't happen, and I think it is because something has gotten more
>>> strict. I have also tried adjusting the offending docstring multiple
>>> ways, and I can't figure out *what* exactly it doesn't like about the
>>> indentation.

...

> $ python
> >>> from docutils.core import publish_parts
> >>> publish_parts(myfunc.__doc__)

> This should make it a bit more obvious when you encounter what I would
> guess to be one of the most likely non-obvious causes of formatting
> errors from docstrings, which is docstrings in a form like:

> def myfunc():
> """This is the first line.
> More lines here.
> Another line.
> So forth."""

> If you check myfunc.__doc__, you'll see that the first line has no
> indentation and all of the remaining lines have indentation:

> This is the first line.
> More lines here.
> Another line.
> So forth.

Interestingly, if you check help(myfunc), the lines are aligned::

myfunc()
This is the first line.
More lines here.
Another line.
So forth.

and IMO, the docstring-extractor should replicate this behaviour.

Günter

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 20.04.2010 10:21, schrieb Guenter Milde:

>> If you check myfunc.__doc__, you'll see that the first line has no
>> indentation and all of the remaining lines have indentation:
>
>> This is the first line.
>> More lines here.
>> Another line.
>> So forth.
>
> Interestingly, if you check help(myfunc), the lines are aligned::
>
> myfunc()
> This is the first line.
> More lines here.
> Another line.
> So forth.
>
> and IMO, the docstring-extractor should replicate this behaviour.

It does -- the indentation of the first line is always stripped
independently of the subsequent lines.

Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)

iEYEARECAAYFAkv3z9MACgkQN9GcIYhpnLBR7QCeOzGQHaA2O4s72t4k5cvW7Zoj
T2gAoKH/HXBXJ8xMXUZApq8PWc1LsCJ6
=woKg
-----END PGP SIGNATURE-----