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

[John Snow]

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