Sphinx, MyST, and Python Docs in 2022

Episode Deep Dive

Guests Introduction and Background

Paul Everett: Developer advocate at JetBrains (PyCharm) and long-time Python community member who focuses on Sphinx and MyST tooling. He is passionate about creating powerful documentation systems, developer workflows, and knowledge bases.

Pradyun Gedem: A Bloomberg software engineer and maintainer on pip who has significant contributions to Python packaging. He is also deeply involved in the Sphinx ecosystem, including theming, MyST, and Sphinx’s developer workflows.

Chris Holdgraf: Director of 2i2c, dedicated to interactive computing infrastructure and Jupyter projects. He works on JupyterHub, Binder, Executable Books, and Jupyter Book, bridging scientific and academic communities with practical, maintainable tooling.

Chris Sewell: A Python developer and data scientist at EPFL in Switzerland, contributing to the Executable Books and MyST projects. He balances scientific workflows, reproducible science, and advanced documentation tools in the Python ecosystem.

What to Know If You're New to Python

If you’re just starting out, this conversation highlights how Python’s ecosystem supports rich documentation, interactive scientific workflows, and user-friendly writing formats. In particular, the episode references tools and packages such as Sphinx, MyST, and Jupyter Book, which can help you create professional-quality documentation even if you are new to coding. Having a basic grasp of Python syntax and file structures will allow you to follow along more smoothly. Below are a few resources to deepen your foundation:

• Python for Absolute Beginners: A comprehensive introduction to Python concepts, syntax, and essential programming skills.

Key Points and Takeaways

1. Why Sphinx Matters to Python Documentation Sphinx powers the official Python documentation, making it the de-facto standard for many open-source Python libraries. It allows you to generate multiple outputs (HTML, PDF, ePub) from a single source, with cross-referencing features that elevate documentation from basic text to a structured knowledge base.
   • Links and Tools:
     • Sphinx Official Site
     • Python Docs (built with Sphinx)
2. MyST’s Role in Bridging Markdown and reStructuredText reStructuredText (reST) is powerful but can be verbose for quick writing. MyST extends Markdown’s simpler syntax to access all of Sphinx’s power (e.g., directives, roles, cross-referencing). This means you can write in familiar Markdown and still leverage advanced doc-building functionality.
   • Links and Tools:
     • MyST Parser
     • GitHub-Flavored Markdown spec (contrasted in the episode)
3. Jupyter Book: Scientific Documentation and Beyond Built on Sphinx and MyST, Jupyter Book lets you create “book-style” documentation with interactive features. It’s especially popular in data science, allowing you to embed Jupyter notebooks, run code, and include outputs dynamically within your docs or tutorials.
   • Links and Tools:
     • Jupyter Book
     • Project Jupyter
4. Power of Directives, Roles, and the Doc Tree Sphinx uses the concept of directives and roles to enrich your text beyond standard markup. These let you insert dynamic content, generate API docs from docstrings, or even embed tests in your documentation. Internally, Sphinx processes a “doc tree” (via Docutils), enabling cross-referencing, linking, and consistent output across formats.
   • Links and Tools:
     • Docutils
     • Sphinx Extension Docs
5. Sphinx Themes and Modern Web Design Older Sphinx themes often felt outdated. Recent theme development—such as Furo, PyData Sphinx Theme, or the Sphinx Book Theme—brings modern design, better navigation, and improved UX. This redesign wave encourages projects to present a polished, inviting face to users.
   • Links and Tools:
     • Furo Theme
     • PyData Sphinx Theme
     • Sphinx-Themes.org Catalog
6. Future-Proofing Python Docs with Collaboration Core Sphinx contributors are tackling new frontiers, including JavaScript-based live previews and improved developer experiences. The conversation called for designers, JavaScript experts, and technical writers to join the Sphinx effort to make the Python ecosystem more polished and accessible.
   • Links and Tools:
     • Sphinx Theme Builder by Pradyun G.
     • Sphinx Auto Build (live reload)
7. Executable Books and Interactive Learning Through the Executable Books project, tools like Jupyter Book integrate code execution into docs, so each example can be run on-the-fly. This concept is central to scientific reproducibility, bridging well-written instructions with verifiable, automated code blocks.
   • Links and Tools:
     • Executable Books Project
8. Sphinx as a Framework Beyond Documentation Sphinx is often used for project documentation, but it can also power websites, blogs, or even knowledge bases by leveraging advanced cross-referencing, search indexing, and theming. Custom extensions make it possible to adapt Sphinx to nearly any content-creation workflow.
   • Links and Tools:
     • Ablog: Blogging with Sphinx
     • Static Sites with Sphinx and Markdown course
9. reST vs. Markdown: Complementary, Not Competing While reStructuredText supports robust, detailed directives, Markdown offers minimal, streamlined syntax. MyST tries to bridge these approaches, letting projects choose whichever style fits best. The unified back-end (Docutils + Sphinx) ensures consistent and powerful output.
   • Links and Tools:
     • CommonMark Spec
10. Cultivating Better Quality through Look and Feel Well-designed themes, clearer content organization, and updated standards not only make docs visually appealing but encourage authors to write more thorough, better-structured documentation. The entire ecosystem improves because contributors can see exactly where new explanations or reorganization is needed.

• Links and Tools:
  • Read the Docs
  • InterSphinx Documentation

Interesting Quotes and Stories

• “Sphinx is an underappreciated miracle.” – A reference to how Sphinx has been continuously maintained for over a decade while juggling Python’s evolution and user demands.
• “We want documentation that’s more like a knowledge base.” – Reflecting the desire to push Sphinx beyond strictly technical docs and into richer, more connected content.
• “When these tools look nicer, we write better documentation.” – The guests emphasized the tight relationship between user-friendly design and higher-quality content.

Key Definitions and Terms

• Sphinx: A documentation generator and toolkit in Python capable of producing multiple formats from a single source.
• Docutils: The underlying text processing system that Sphinx builds upon, defining the document tree (doc tree) and transformations.
• MyST: A Markdown flavor that includes directive and role support to access advanced Sphinx features in a familiar Markdown format.
• Directive: A block-level extension or command in Sphinx that performs special actions (e.g., embedding images, code blocks, or custom logic).
• Role: An inline markup extension in Sphinx that can format or link text in specialized ways (e.g., cross-referencing code).
• Jupyter Book: A system built on Sphinx and MyST for producing book-style documentation that can contain interactive computations from Jupyter notebooks.

Learning Resources

• Python for Absolute Beginners: Ideal for anyone new to coding and Python, covering core language basics, data types, and workflows.
• Static Sites with Sphinx and Markdown: A free course by Paul Everett teaching you how to create documentation and even full static sites using Sphinx + Markdown.
• Jupyter Book Documentation: Official reference and tutorials on building interactive, book-like docs.
• Sphinx Official Documentation: For more advanced directives, extension management, and theming guidelines.

Overall Takeaway

Sphinx remains a cornerstone for Python documentation, enabling robust output and advanced features through its doc tree and extension system. Innovations such as MyST, modern Sphinx themes, and Jupyter Book are making high-quality docs easier than ever to create. With the community’s ongoing collaboration—particularly in web design, user experience, and extension development—the future of Python documentation looks bright and more accessible for projects of all sizes.