The Riddle of the Intersphinx: Configuration and Cross-Reference Composition
Brian Skinn
https://www.pyohio.org/2019/presentat...
[Sphinx](http://www.sphinx-doc.org) is a documentation generator used by the [core Python documentation](https://docs.python.org/3/library/ind...) and numerous other packages such as [SciPy](https://docs.scipy.org/doc/scipy/refe..., [Django](https://docs.djangoproject.com/en/), and [Blender](https://docs.blender.org/api/current/). Sphinx supports cross-references across project boundaries via its ['intersphinx' extension](http://www.sphinx-doc.org/en/stable/e..., 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](http://www.sphinx-doc.org/en/stable/m...) is convenient for some cases, but is unhelpful when a given object name is ambiguous (e.g., with the Python [max() builtin](https://docs.python.org/3/library/fun...) versus [numpy.ndarray.max](https://docs.scipy.org/doc/numpy-1.13....
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.
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.
===
https://pyohio.org
A FREE annual conference for anyone interested in Python in and around Ohio, the entire Midwest, maybe even the whole world.
Produced by NDV: / @nextdayvideo
Sun Jul 28 13:45:00 2019 at Hays Cape