feat: Create .inv files for downstream projects to consume

[NickCrews]

Hi again! Not sure if this is a feature I haven't found yet. Ibis is using quartodoc to build their API reference. I have a downstream library that uses ibis. In the docs for that lib, I would like to be able to link to items in the ibis docs. It looks like quartodoc is currently only able to consume .inv files, but not create them, is that right? What would it take to make this happen? This is mostly a nice-to-have so I wouldn't put it anywhere near the top of your todo. Thank you!

[machow]

Hey, thanks for the nudge!

It looks like quartodoc is currently only able to consume .inv files, but not create them, is that right?

That's right, but we could generate a .inv pretty easily, since we use sphobjinv under the hood.

Alternatively, if this seems like an okay option. If you set fast: true in your interlinks config, then it should save your inventory file using the .txt extension. AFAIK this is usable by sphinx.

With some minor tweaks, we could make it so other quartodoc projects could use these files like this (similar to sphinx's config):

interlinks:
  sources:
    mypackagedocs:
      url: https://mypackagedocs.com/

      # look for objects.txt, rather than objects.inv
      inv: objects.txt

WDYT of that? It's likely that in the future quartodoc will to switch to saving all the downloaded inventories as .txt, since it speeds up doc generation (due to some quirks in how filters work; and the speed of parsing json in quarto).

Otherwise, it seems okay to add a flag to save an objects.inv file. The downside is that these files are a bit weird (they are a few lines plaintext, followed by gzipped content), and modern webservers are capable of gzipping files anyway.

[NickCrews]

It looks like ibis already has fast: true set, and when I build the ibis docs locally there is a objects.txt generated in the /docs/ directory, but I don't see anything at
https://ibis-project.org/objects.txt, or any .*objects.* entry in https://ibis-project.org/sitemap.xml. Any idea where this file is getting lost between getting generated and published?

[NickCrews]

With some minor tweaks, we could make it so other quartodoc projects could use these files like this (similar to sphinx's config):

Why not skip the config, and first just look for objects.inv and use that if its there. if 404 then fallback to objects.txt? Avoid all the config! :)

Or actually, I'm building mypackage's docs with mkdocs and mkdocstrings, not quarto and quartodoc. I don't understand the diff between .inv and .txt really, will mkdocstrings be able to parse objects.txt? If it can't, then I would say that we should

1. give in and be forced to produce the standard .inv
2. go full on and convince the entire ecosystem to support .txt if that really is better.
   I don't want to introduce fragmentation, I want there to be one file format.

[machow]

Or actually, I'm building mypackage's docs with mkdocs and mkdocstrings

Good point. @pawamoy, do you know if mkdocstrings python can read inventories stored as a .txt? (or if that'd be a useful thing to add? It's the unzipped .inv file, and I think sphinx can handle .txt, but it's not common in the wild.).

RE

but I don't see anything at https://ibis-project.org/objects.txt

Does setting resources: in _quarto.yml work?

project:
  type: website

  ...

  resources:
    - objects.txt

quarto sometimes requires manually including files into the build.

[NickCrews]

Does setting resources: in _quarto.yml work?

It does! Thank you! I'm going to hold off on suggesting this feat to Ibis until we resolve the .inv/.txt question, because perhaps they will need to switch to .inv

[pawamoy]

@machow mkdocstrings-python currently only supports .inv files (well, the extension does not matter, but we always try to decompress it). If Sphinx officially supports .txt files, which are just the decompressed version of .inv files, then yeah, we can totally add support for them in mkdocstrings-python too. Maybe we would even default to generating .txt inventory files, since as you said HTTP servers can gzip contents themselves, and text files would actually be readable anywhere, improving the UX/DX.

[machow]

I'll plan to add a snapshot test for rendering a sphinx site that consumes a .txt file we produce