Re: [PATCH 16/22] qapi/parser: add docstrings

[John Snow]

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