bskinn/sphobjinv

Provide JSON export that puts items in a list

Opened this issue · 4 comments

machow commented

Hey, sphobjinv has been a total lifesaver for understanding the sphinx inventory format, while working on quartodoc!

(cc @pawamoy, who I think might use parts of sphobjinv for mkdocstrings, though maybe just exports to .inv files? :)

Is your feature request related to a problem? Please describe.

Currently, exporting to JSON format puts items on the top-level object, with number keys:

{
  "project": "nbformat",
  "version": "5.7",
  "count": 51,
  "0": {"name": "jsonschema.exceptions.ValidationError", "domain": "py", "role": "class", "priority": "-1", "uri": "api.html#nbformat.ValidationError", "dispname": "-"}, 
  "1": {"name": "nbformat", "domain": "py", "role": "module", "priority": "0", "uri": "api.html#module-$", "dispname": "-"}, 
  "2": ...
}

This works pretty well. However, it can feel a bit tricky to grab just the items, and the number keys feel a bit surprising.

Describe the solution you'd like

I wonder if putting items into a list might help with grabbing things / removing key entries?:

{
  "project": "quartodoc",
  "version": "0.0.9999",
  "count": 106,
  "items": [{"name": "quartodoc.get_function", ...
}

Describe alternatives you've considered

Right now, I use the current format and then process it to the proposed one 😅. This works pretty well, so I could see sticking with the existing format to preserve backwards compatibility.

pawamoy commented

@machow we actually don't use sphobjinv, even though it's a great package 😄
It was easy enough to implement our own inventory reader/writer, so I opted out of adding another dependency.

bskinn commented

@pawamoy Are there any custom formats that you're using in mkdocstrings that it would be useful to also have in sphobjinv?

Might as well maximize interop!

pawamoy commented

Not using it yet, but at some point it will be interesting to provide a JSON inventory, with more than just existing objects (and their relative URIs): I'd like to include each and every reference to these objects within the code base. Kinda like backlinks: object a.b.c is used in a.w.x and a.y.z functions. This would allow "Find references"-like features in static site generators such as MkDocs. It's really just an idea for now 🙂

bskinn commented

Ah, nod, could autogenerate an index, basically... or, at least an index of every cross-references mention. Would be neat to have!

  • 👍1