Proposal Summary
To upgrade the interactive documentation experience of IPython and Jupyter to allow inline graphs, navigation, and indexing, and to support features currently only available on hosted websites.
Papyri
Python has multiple stories for documentation: docstrings, narrative documentation built via Sphinx and hosted online, and Dynamic Tutorials by downloading notebooks. However, none of these offer a complete documentation experience. Via a reusable framework we call Papyri, included in IPython/Jupyter, this proposal aims to offer a state-of-the-art documentation experience to end-users. The current proof of concept allows library authors to publish a semantic Intermediate Representation Documentation format (IRD). On users’ machines, tools can leverage IRD to provide access to the full richness of the Python Ecosystem documentation. This project represents the key for the development, quality, ease of use, and discoverability in a growing Python ecosystem. Additionally, this framework will open the door to several other valuable features, such as allowing docstrings to be written in the widely-used markdown format, better configuration of end-user appearance and preferences, translations and domain-specific alternatives, indexing, and others.