On Fri, Mar 7, 2025 at 7:37 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@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 <js...@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.
