Description
Sphinx is a documentation generator used by the core Python documentation and numerous other projects in the Python ecosystem. Sphinx supports cross- references between documentation sets via its ‘intersphinx’ extension; however, proper configuration is not always straightforward, and cross- references can be finicky to craft correctly. This talk aims to demystify these riddles of intersphinx usage.
Sphinx is a documentation generator used by the core Python documentation and numerous other packages such as SciPy, Django, and Blender. Sphinx supports cross- references across project boundaries via its 'intersphinx' extension, which uses data from an objects inventory file generated by Sphinx when building HTML docs. However, configuration of the intersphinx mappings to external documentation and correct composition of the cross-references to specific external objects can both be challenging to achieve, as the necessary reference syntax can vary in a non-obvious way. Related messages/warnings issued during the Sphinx build process, if enabled, are useful for identifying that a problem exists, but are typically of minimal help in fixing the broken references. The :any: role is convenient for some cases, but is unhelpful when a given object name is ambiguous (e.g., with the Python max() builtin versus numpy.ndarray.max).
In this talk, I will describe a (mostly) systematic approach to intersphinx configuration and usage, including locating the inventory for an external docset; decoding and parsing the inventory to obtain the information needed for a functional intersphinx reference; and constructing the cross-reference from this information. As I hope to demonstrate, using intersphinx is quite easy, as long as you know where to look for key information, and what to do with it.