veyepar: The Riddle of the Intersphinx: Configuration and Cross-Reference Composition

Author(s):	Brian Skinn
Location	Hays Cape
Date	jul Sun 28	Days Raw Files
Start	July 28, 2019, 1:45 p.m.	First Raw Start	July 19, 2019, 9:16 a.m.
Duration	0:30:0	Offset	9 days, 4:28:36
End	July 28, 2019, 2:15 p.m.	Last Raw End	July 19, 2019, 10:16 a.m.
Chapters	00:00 0:00:03 0:14:16
Total cuts_time	24 min.

https://www.pyohio.org/2019/presentations/137
raw-playlist raw-mp4-playlist encoded-files-playlist host archive tweet mp4 svg png

assets release.pdf The_Riddle_of_the_Intersphinx_Configuration_and_CrossReference_Composition.json
logs
Admin: episode episode list cut list raw files day marks day marks day image_files

State:
Locked:	clear this to unlock
Locked by:	user/process that locked.
Start:	initially scheduled time from master, adjusted to match reality
Duration:	length in hh:mm:ss
Name:	Video Title (shows in video search results)
Emails:	email(s) of the presenter(s)
Released:	has someone authorised pubication
Normalise:
Channelcopy:	m=mono, 01=copy left to right, 10=right to left, 00=ignore.
Thumbnail:	filename.png
Description:	[Sphinx](http://www.sphinx-doc.org) is a documentation generator used by the [core Python documentation](https://docs.python.org/3/library/index.html) and numerous other packages such as [SciPy](https://docs.scipy.org/doc/scipy/reference/), [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/ext/intersphinx.html#module-sphinx.ext.intersphinx), 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/markup/inline.html#role-any) 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/functions.html#max) versus [numpy.ndarray.max](https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.ndarray.max.html)). 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. markdown
Comment:	production notes