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.
On Wednesday, 14 October 2020 at 19:45:17 UTC+1 Luc Saffre wrote:
> 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
>
>
>
> On 14.10.20 16:57, Andrew Porter wrote:
>
> 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
>
>
>
> On Wednesday, 14 October 2020 at 12:48:20 UTC+1 Luc Saffre wrote:
>
>> Try setting autodoc_inherit_docstrings
>> <https://www.sphinx-doc.org/es/master/usage/extensions/autodoc.html#confval-autodoc_inherit_docstrings>
>>
>> to False.
>>
>> Luc
>>
>>
>> On 14.10.20 10:36, Andrew Porter wrote:
>>
>> 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.
>>
>> --
>> 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 [email protected].
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/sphinx-users/d845e746-db09-4712-ad82-058d34d591efn%40googlegroups.com
>>
>> <https://groups.google.com/d/msgid/sphinx-users/d845e746-db09-4712-ad82-058d34d591efn%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>>
>>
>>
> --
> 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 [email protected].
>
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/69bf03b2-9ae1-4023-9674-11a6b3c6f069n%40googlegroups.com
>
> <https://groups.google.com/d/msgid/sphinx-users/69bf03b2-9ae1-4023-9674-11a6b3c6f069n%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
>
>
>
--
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 [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/sphinx-users/241c5c75-2b9d-423f-90a4-21593c8c7cedn%40googlegroups.com.
