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 On 15.10.20 10:28, Andrew Porter wrote: > 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] > <mailto:[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 > <https://groups.google.com/d/msgid/sphinx-users/241c5c75-2b9d-423f-90a4-21593c8c7cedn%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/ab318021-d22d-8c2b-9f2c-4e4c65581051%40gmail.com.
