Let's be honest: we like the projects we use to be well-documented, but we almost never have time to document ours. How can we make writing documentation for our Data Science project be as pleasant as possible?
In this workshop you will document a Data Science project using Sphinx, leveraging Markdown and Jupyter notebooks, and we will deploy the result to Read the Docs.
The talk will loosely follow the structure of the official Sphinx tutorial, using Markdown instead of reStructuredText to be more approachable for contributors:
-1. Creating your Sphinx project (15 minutes)
Tutorial introduction, basic project scaffolding using sphinx-quickstart, explanation of the different files that were created.
-2. MyST vs reStructuredText (5 minutes)
Differences between the two markup languages, current status of the ecosystem, pros and cons.
-3. Write Markdown, build HTML (15 minutes)
First steps writing prose documentation using MyST, a flavor of Markdown compatible with Sphinx that adds roles and directives from reStructuredText. Building of HTML documentation using the Sphinx Makefile.
-4. Customizing Sphinx (10 minutes)
Enabling extensions: sphinx.ext.durations to measure performance, furo to use different HTML themes.
-5. Adding cross references (10 minutes)
Adding cross references to other pages of the documentation, specific targets, and objects outside our own project using intersphinx.
-6. Integrating Jupyter notebooks (10 minutes)
Using Jupyter notebooks as pages for the Sphinx documentation, tips and tricks for interactive widgets.
-7. Documenting code automatically (15 minutes)
Leveraging Sphinx code documentation capabilities. Using autodoc to integrate docs from Python docstrings.
-8. Deploying to Read the Docs (10 minutes)
Creating a project on Read the Docs for automatic deployment of the documentation. Enabling pull request reviews.