autodoc reports errors for dict module variable

[Andrew Porter]

Hello,

I'm using autodoc in Sphinx 3.2.1 and have a problem where it reports formatting errors from what I think is the `dict` docstring rather than my code. I have a module (`node`) which contains a dict:

    #: Colour map to use when writing Invoke schedule to terminal.
    SCHEDULE_COLOUR_MAP = {"Schedule": "white",
                       "Loop": "red",
                       "GlobalSum": "cyan"}

This module is then made available in the __all__ list of the __init__.py of the package

containing the module, i.e. I have an __init__.py that contains:

    from nodes.node import SCHEDULE_COLOUR_MAP

    __all__ = ['SCHEDULE_COLOUR_MAP']

   

When running Sphinx autodoc I see:

    /blah blah/nodes/__init__.py:docstring of psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:3: WARNING: Unexpected indentation.

    /blah blah/nodes/__init__.py:docstring of psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:4: WARNING: Block quote ends without a blank line; unexpected unindent.
    /blah blah/nodes/__init__.py:docstring of psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:7: WARNING: Unexpected indentation.
    /blah blah/psyir/nodes/__init__.py:docstring of psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:9: WARNING: Inline strong start-string without end-string.

As you can see, I've tried explicitly adding a docstring for the dict using the `#:` markup but that doesn't seem to get picked up.

I get exactly the same problem with a different dictionary in a different module.

Am I doing something wrong here?

(FYI, you can reproduce this problem by cloning https://github.com/stfc/PSyclone.git, cd PSyclone; pip install .; cd doc/reference_guide; make html)

Many thanks,

Andy.

[Luc Saffre]

Try setting autodoc_inherit_docstrings to False.

Luc

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/d845e746-db09-4712-ad82-058d34d591efn%40googlegroups.com.

   

[Andrew Porter]

Thanks Luc. I tried adding:

    autodoc_inherit_docstrings = False

to my conf.py, wiping all generated rst files and documentation and building again but to no avail - I still get the same warnings :-(

Thanks,

Andy

[Luc Saffre]

Okay...  I think i can confirm your assumption that autodoc is trying to render the docstring of the dict class object:

>>> print(dict.__doc__)
dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
    (key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
    d = {}
    for k, v in iterable:
        d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs
    in the keyword argument list.  For example:  dict(one=1, two=2)

Next idea: What is this "#:" syntax for specifying docstring? Seems that I missed some recent evolution of the Python language? What happens when you specify your docstring using the classical way:

    SCHEDULE_COLOUR_MAP = {"Schedule": "white",
                       "Loop": "red",
                       "GlobalSum": "cyan"}
    "Colour map to use when writing Invoke schedule to terminal."

Luc

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/69bf03b2-9ae1-4023-9674-11a6b3c6f069n%40googlegroups.com.

[Andrew Porter]

Thanks Luc. I discovered the "#:" on https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html (under autoattribute). Adding a docstring on the line immediately after the colour map makes no difference sadly :-( In case it helps, the rst generated by autodoc contains:

    - :py:data:`SCHEDULE_COLOUR_MAP`

    .. autodata:: SCHEDULE_COLOUR_MAP
       :annotation:

       .. code-block:: text

          {'Assignment': 'blue',
           'BuiltIn': 'magenta',

           ....}

Thanks,

Andy.

[Luc Saffre]

At least one good thing: I learned about the "#:" feature (i.e. the possibility to add documentation without actually defining a docstring).

At the moment I have no more quick idea. And -forgive me- I prefer to not dive deeper into this, I have so many other important things to do...

Luc

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/241c5c75-2b9d-423f-90a4-21593c8c7cedn%40googlegroups.com.

[Andrew Porter]

Not to worry - thanks for your time Luc.

Cheers,

Andy.

[Komiya Takeshi]

Hi,

I think this is the same as this issue:
https://github.com/sphinx-doc/sphinx/issues/8547
And there is no good way to resolve it well.

Thanks,
Takeshi KOMIYA

2020年10月14日(水) 16:36 Andrew Porter <trackst...@gmail.com>: