On 4/25/21 9:27 AM, Markus Armbruster wrote:
Another ignorant doc string markup question... how am I supposed to see
that exprs and docs are attributes, and not global variables?
The syntax is apparently supposed to be :py:attr:`MyClass.attr`. Though,
it doesn't seem to be working for me. I can write :py:attr:`bzbxglkdsgl`
and the build succeeds. I gotta hunch:
Sphinx was designed to parse ReST written by hand. The " .. py:method::"
directives are ones you'd use when using sphinx in that style. Those
directives are what create an object in Sphinx's cross-reference system.
Later, if you use :py:meth:`foo`, it references that specific object.
Sphinx autodoc is a system that parses your code and automatically
generates py:method:: and py:class:: directives for you, allowing the
reference syntax to work.
MY HUNCH is that for field list markup within a docstring -- things like
:ivar: -- that there is not any corresponding object being created,
rendering cross-references for things at that scope when using autodoc
ineffective.
BOO, BOO, A THOUSAND TIMES BOO TO THIS.
Argh, yep.
If I use:
.. py:attribute:: exprs
Resulting parsed expressions.
instead of
:ivar exprs: Resulting parsed expressions
then the syntax :attr:`qapi.parser.QAPISchemaParser.exprs` does resolve
into a clickable hyperlink on the rendered output.
____ ___ ___ ___ _
| __ ) / _ \ / _ \ / _ \| |
| _ \| | | | | | | | | | |
| |_) | |_| | |_| | |_| |_|
|____/ \___/ \___/ \___/(_)
Sigh. Well, while I'm here doing the research and talking to myself, the
syntax :attr:`exprs` also works when you have the target defined. It
doesn't have to be as verbose. With my testing setup of using the
default role of "any", even just `exprs` works.
I wonder if there's the possibility of having sphinx enhance :ivar: and
:cvar: to automatically create the same kind of reference target as
py:attribute:: does.
Problems for later.
For now ...
``.exprs`` and ``.docs``?
--js
