Hi @Yoshanuikabundi, thanks for the PR and detailed explanation!

Looking at Sphobjinv's docs (from @bskinn):

{dispname}
Default cross-reference text to be displayed in compiled documentation.
Constraints:

• MUST have nonzero length
• MAY contain internal whitespace (leading/trailing whitespace is ignored)

...it seems newlines are indeed valid inside dispname. @bskinn could you confirm? 🙏

Out of curiosity @Yoshanuikabundi, could you show some example dispname values that are present in the mentioned inventories?

...it seems newlines are indeed valid inside dispname.

My first reaction: I believe this is >incorrect<, and in fact newlines are invalid anywhere in any field in a v2 objects.inv file.

I would have to dig back into the Sphinx code to be sure, but I'm pretty sure that Sphinx processes the decoded objects.inv payload line by line, always treating each line separately as a candidate inventory item. Any line that doesn't parse as a valid inventory object is silently ignored, leading to the behavior noted by OP:

However, while Sphinx discards any inventory lines that do not parse (such as the continuation line) ...

I wrote all of of the higher-level components of the sphobjinv API to mimic this behavior, for maximum compatibility. I don't have a ticket for it at the moment, but a good feature for sphobjinv (and for Sphinx too, for that matter) would be to emit a warning if any lines in an inventory were ignored due to syntax mismatch. (No ticket at the moment on sphobjinv; I opened sphinx-doc/sphinx#8825 some time ago, but neither I nor anyone else has worked on it, AFAIK.)

My opinion here is that mkdocstrings revise to match Sphinx's behavior, and not add handling for newlines in dispname.

This seems to me to be an XY problem. IMO, dispnames should be short, at most a small phrase; and, thus any text substantial enough to need a newline is not appropriate for a dispname, whether or not the dispname machinery happens to work for the desired use-case. In the specific examples I found below, the majority appear to be figure captions -- perhaps the intention for these is to create a Table of Figures? If so, I would think these newlines within the dispnames would be problematic if included in that ToF.

In any event, I would guess that the best solution to this documentation need is a Sphinx extension of some kind.

I found the mismatching objects in the OpenEye Toolkits objects.inv with the following:

>>> import sphobjinv as soi
>>> from pathlib import Path
>>> cbdata = Path('objects.inv').read_bytes()
>>> bdata = soi.decompress(cbdata)
>>> tdata = bdata.decode()
>>> [l for l in tdata.splitlines()[4:] if not soi.re.p_data.match(l)]  # [4:] skips the header

... list of syntax-mismatching lines ...

I then exported the decompressed contents to disk with:

>>> Path('objects-manual.txt').write_text(tdata)

And searched for the mismatching lines. Here are some examples of full entries with internal newlines from that same objects.inv:

figure_fragmentation std:label -1 medchemtk/fragmentation.html#figure-fragmentation Example of fragmentation (A) input molecule
(B) fragments returned by the OEGetRingChainFragments function

figure_oe2datomdisplay_getpropertyoffset std:label -1 depicttk/OEDepictClasses/OE2DAtomDisplay.html#figure-oe2datomdisplay-getpropertyoffset The property offset vector is relative to coordinates returned by
the OE2DAtomDisplay::GetCoords method

figure_oe2dbonddisplay_getpropertyoffset std:label -1 depicttk/OEDepictClasses/OE2DBondDisplay.html#figure-oe2dbonddisplay-getpropertyoffset The property offset vector is relative to the middle of the
displayed bond

figure_ring_sssr std:label -1 oechemtk/ring.html#figure-ring-sssr Example of SSSR
SSSR is not an invariant subset of all possible rings; (a), (b) and (c) depict the three equally valid SSSR of the bridged structure (on the left)

posit_cross_docking_results std:label -1 dockingtk/theory/shapefit.html#posit-cross-docking-results SHAPEFIT Cross Docking Results: Probability of finding a good pose based on bound-ligand
fit-ligand TanimotoCombo similarity.  Standard docking results
are essentially the same and follow the same trajectories
flattening out as they hit their limit of accuracy.  While SHAPEFIT
performs worse at low similarities it continually increases as
similarity increases.

posit_heat_map std:label -1 dockingtk/theory/pose_stub_tk.html#posit-heat-map POSIT Probability Map: Given a 2D similarity (in this case the MACCS 166 descriptor set [Durant-2002])
and a 3D similarity (TanimotoCombo) posit computes a
probability of finding the correct pose based on an analysis of
historical and experimental data.

One thing this discussion points to for sphobjinv, is a need for additional specificity on that docs page.

The invalidity of newlines in any field is implicit in the use of "data line" in this sentence on that page (emphasis added):

The descriptions below have been updated to reflect this and to provide more detailed information on the constraints governing each field of an objects.inv data line.

But the description could use a more direct statement of the strict limitation of each data item being constrained to a single line of the decompressed inventory source.

Thank you @bskinn!

My initial reaction was similar: even if newlines were valid, how they are rendered depend on the output format (HTML, Markdown, PDF, etc.) and so I wasn't sure it made sense to support them.

Thanks a lot for searching for and finding examples in the mentioned inventories. These "display names" definitely look like descriptions, not names, so I'd be inclined to say they are invalid.

In short, I agree with @bskinn's reasoning and suggestions, and will probably not merge this PR as it is. Instead we should log warnings on invalid lines.

In:

https://github.com/sphinx-doc/sphinx/blob/master/sphinx/util/inventory.py#L113-L121

...non-matching lines are indeed skipped.

That sounds very reasonable to me! The offending lines are mostly automatically generated from figure/image captions and are very unlikely to be desired in any cross reference. I'll revise this PR to simply discard lines that can't be parsed rather than append them to the previous entry, but I won't be able to get to this immediately.

I'd be against issuing a warning - the warning would usually not be actionable by the users as by definition it comes from another documentation site. In fact, in this case even the docs that the inventory was from wouldn't be able to action the warning as its more or less a misjudgement in a Sphinx plugin. I'd worry it'd almost always just be noise, which mkdocs is usually good about minimising. I don't believe Sphinx warns.

Ah, you're completely right @Yoshanuikabundi, good point. No warning log then! And no worries, I'll take it from here if you don't have the time 🙂

Great, thanks @pawamoy!