Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible

[John Snow <jsnow@redhat.com>]

On 10/1/20 4:54 AM, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
> 
>> On 9/30/20 4:47 AM, Markus Armbruster wrote:
>>> Sadly, the fact that start_if() and end_if() are functions isn't
>>> immediately obvious anymore.
>>> I've seen :func:`start_if` elsewhere.  Is this something we should
>>> or
>>> want to use?
>>
>> Looks like `start_if()` works just fine too. If you are hard-set in
>> wanting to see those parentheses I can use this style, but admit I am
>> not likely to use them myself in newer docstrings, and there's no way
>> to enforce their presence OR absence that I am aware of.
> 
> Well, there's no way to enforce presence or absence of ` either, right?
> 

Yeah, just a warning that enforcing mechanical consistency along these 
lines is not something we can do at the moment.

(We maybe could by creating a sphinx plugin, but that's a bridge to 
cross much, much later. Anything is possible with time, engineers, and 
money, right?)

> Aside: checking the enclosed text resolves as a cross-reference could
> provide good-enough enforcement of absence, but enclosing stuff in `
> when you shouldn't is probably the lesser issue.
> 
>> I'll bake that change in for now until I see another reply.
> 
> Since this is a side show right now, consider the arguments raised so
> far, use your judgement, and move on to the main show.
> 

Keeping emails out of my inbox is presently the nicest thing :)

Thanks for looking.

--js