Not to worry - thanks for your time Luc. Cheers,
Andy. On Thursday, 15 October 2020 at 09:11:23 UTC+1 Luc Saffre wrote: > 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]. > > 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/f9caf533-487d-4cc1-a028-3840d066cd4bn%40googlegroups.com.
