Fix API Reference header formatting for Intersphinx

[analog-cbarber]

It would be nice if the documentation published an intersphinx objects.inv file so that other projects
can use it for cross linking in their documentation.

This only will require adding enable_inventory to the mkdocstrings configuration in mkdocs.yml:

  - mkdocstrings:
      # generate objects.inv sphinx inventory file in site/ dir to support external cross references
      enable_inventory: true

See https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories

[jayqi]

@analog-cbarber I haven't seen this before—very cool and thanks for highlighting it!

According to the docs you linked, we should be doing this already because of mkdocstrings' default configuration.

Reciprocally, mkdocstrings also allows to generate an inventory file in the Sphinx format. It will be enabled by default if the Python handler is used, and generated as objects.inv in the final site directory. Other projects will be able to cross-reference items from your project!

It looks like our 0.7.0 release build that published the https://cloudpathlib.drivendata.org/stable/ docs was using mkdocstrings v0.18.0, which should support this feature. I see an objects.inv file that exists at https://cloudpathlib.drivendata.org/stable/objects.inv already. The intersphinx standard is new to me, so I don't really know if the inventory file is correct. Can you try to use it and see if it works for you?

[analog-cbarber]

That file is there, but for some reason lacks entries for some classes such as S3Path. There are entries for the methods but not the class itself. So I cannot link directly to the class using something like:

"""
    See: [cloudpathlib.S3Path][cloudpathlib.s3.s3path.S3Path]
"""

So I either need to use something like [cloudpathlib.S3Path][cloudpathlib.s3.s3path.S3Path.anchor]
or just manually put in the entire URL [cloudpathlib.S3Path][https://cloudpathlib.drivendata.org/stable/api-reference/s3path/#cloudpathlibs3path]

I wonder if writing ::: cloudpathlib.s3.s3path.S3Path in s3path.md results in just the members of S3Path
being included and not S3Path itself?

FYI, you can use the sphobjinv program, installable by pip to unpack your objects.inv file to check its contents.

[pawamoy]

When using ::: some.path, you must either enable the show_root_heading or show_root_toc_entry option so that at least there's a (hidden) heading, and therefore some.path is added to the inventory.

[analog-cbarber]

When using ::: some.path, you must either enable the show_root_heading or show_root_toc_entry option so that at least there's a (hidden) heading, and therefore some.path is added to the inventory.

Should that be the default?

[pawamoy]

It's already the default, though maybe it was not at the time the cloudpathlib docs were built.

[pjbull]

@analog-cbarber latest stable docs should have been built and deployed two weeks ago. Does this work now?

[jayqi]

I expect we may still have an issue is that we (probably me) made some formatting choices that don't play nicely with the assumptions of the Intersphinx API publisher. This will require some deliberate changes to fix.

[analog-cbarber]

Nothing has changed. There is still no entry for the classes themselves.