Re: [PATCH 57/57] docs/qapidoc: Add "the members of" pointers

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2142 bytes --]

On Fri, Mar 7, 2025 at 7:37 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Add "the members of ..." pointers to Members and Arguments lists where
> > appropriate, with clickable cross-references - so it's a slight
> > improvement over the old system :)
> >
> > This patch is meant to be a temporary solution until we can review and
> > merge the inliner.
> >
> > The implementation of this patch is a little bit of a hack: Sphinx is
> > not designed to allow you to mix fields of different "type"; i.e. mixing
> > member descriptions and free-form text under the same heading. To
> > accomplish this with a minimum of hackery, we technically document a
> > "dummy field" and then just strip off the documentation for that dummy
> > field in a post-processing step. We use the "q_dummy" variable for this
> > purpose, then strip it back out before final processing. If this
> > processing step should fail, you'll see warnings for a bad
> > cross-reference. (So if you don't see any, it must be working!)
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> Yes, it's a hack, and possibly fragile, but it'll all go away when the
> inliner lands.  I understand the inliner already exists, but you're
> holding it back to not balloon the series even more.
>

Just couldn't find any other way to do it with less SLOC. It's a weird
limitation in the bowels of Sphinx, and the Field classes aren't factored
aggressively enough to just write my own new Field subclass without also
having to do a lot of re-implementation that touches a lot of APIs I'd
rather not muck around with: I literally think that approach, while
"cleaner" in the traditional sense, is likely *more* porcelain than what
I've done here.

Thought it was better to just let Sphinx do whatever it does in make_xref,
and then make some tactical edits on the tail.

Could write a John Steinbeck novella's analysis on all the other approaches
I tried and why I ruled them out, but. Eh. Just read a John Steinbeck
novella instead if you want to.


> I'm on board.
>
>
Thank goodness.

[-- Attachment #2: Type: text/html, Size: 3169 bytes --]