Jumping into a Documentation Journey with Sphinx and Jupyter
Carol Willing
- Audience level:
- Novice
- Category:
- Python Libraries
Description
Learn how the intermediate features of Sphinx, such as extensions, templates, and document conversion, combined with Jupyter Notebooks gave timely and interactive information to developers and early users of JupyterHub.
Abstract
# Jumping into a Documentatation Journey with Sphinx and Jupyter
## I. Background
From Science to Data Science to Education, Project Jupyter notebooks have been widely used for interactive, collaborative computing. Project Jupyter, including JupyterHub, has a very fluid, active, and distributed development process. While the process is great for rapid innovation and development, the pace presented some unique challenges in delivering timely and accurate documentation to developers and end users. An additional challenge was offering documentation that would be understandable to end users that are not developers.
## II. Project Jupyter's Commitment to Documentation
IPython Notebook split in mid-2015 into Jupyter projects and the IPython kernel. Jupyter notebook would now be language agnostic to allow researchers to use kernels, such as IPython, for executing the computer language operations. This resulted in the project growing from a small handful of repos to over 30 development repos by different developer teams. The end result was documentation lagged and fell out of date.
Project Jupyter leadership decided to include documentation as a key element of the Project's roadmap. From this the Jupyter Team began building a culture of excellence around its documentation and began recognizing the benefits of better communication, greater feedback on features, and more organized release rollouts.
### a) Jupyter Notebooks and Multimedia as Documentation
* Jupyter Notebooks in Sphinx Documentation
* Pictures, GIFs, and Videos for capturing state and transitions
* Input and Output formats should meet the needs of developers and users
### b) Extending Sphinx for better documentation
* Built In and Third Party Extensions
* Custom Templates
* Document formats and conversion
### c) Convenience of Read The Docs and GitHub
Attention to detail and consistency of configurations give documentation a familiar look and feel across projects. Little touches, such as making sure the link to documentation is in every GitHub repo description, give the user a more pleasant, familiar, and efficient documentation experience.
### III. Write The Docs and Journey Together to Jupyter
Documentation is cool!