Sphinx and Markdown around the world in 2021

2021-12-20T00:00:00Z

Read the Docs has been committed to improving the accessibility and user experience of Sphinx since the start, and that includes the markup language in which the documentation is written. Years ago, after carefully listening to users, we announced recommonmark to help bridging the immense popularity of Markdown with the powerful capabilities of Sphinx. (It is now deprecated in favor of MyST - keep reading to know more.)

It is no surprise that Markdown is in such demand: thanks in large part to the huge popularity of GitHub, Markdown is nowadays the most widely used markup language in open-source projects, ahead of reStructuredText, the second in the list, by an order of magnitude.

This year, thanks to the CZI Grant we received last year and the effort of other communities, especially the Executable Book Project, we have devoted lots of resources to help consolidate Markdown as a compelling markup language for Sphinx.

Writing Markdown in Sphinx

To that end, we recognized the potential of MyST as a successor of recommonmark, and deprecated the latter in favor of MyST-Parser. To start writing Markdown in Sphinx, you need to follow three steps:

Install MyST-Parser: pip install myst-parser
Add myst_parser to the list of Sphinx extensions:

extensions = [
    # ...other extensions
    "myst_parser",
]

Start writing content in *.md files!

You can find more information in the MyST-Parser documentation.

Talks and workshops at conferences

Luckily the migration to MyST-Parser was trivial for most projects, but we still wanted to spread the word about the best practices for creating Sphinx projects on Read the Docs using MyST Markdown. We set the goal of presenting at every large scientific Python event out there, and all our proposals were accepted [1]! Throughout 2021, we were present in several events:

We conducted a networking session and a sprint about documentation at SciPy US, and in that event we were kindly invited to the sktime documentation sprint.
We delivered a 90 minutes tutorial called “Document your scientific project with Markdown, Sphinx, and Read the Docs” at PyData Global, and we repeated a 120 minute version in Spanish language at the SciPy Latin America.
And we also gave shorter talks at more broadly focused events: PyCon Latam and PyCon Spain.

We have generated workshop material that everybody is welcome to use:

A main repository containing some introductory slides about Sphinx, and detailed notes of every step of the tutorial.
A supporting repository with a tiny Python library that gets used during the tutorial, inspired by the one used in the official Sphinx tutorial we authored with the help of the Sphinx community.

And finally, we have also developed an interactive web application to translate small bits of reStructuredText to MyST Markdown.

[1]	We also have submitted a proposal for SciPy India, which was postponed to January 2022. EuroSciPy and SciPy Japan didn’t happen in 2021.

Future plans

We are excited to see that the Executable Books team has released myst-docutils, which should help docutils parse CommonMark directly and possibly pave the way for Sphinx to parse Markdown without the need of third party extensions. Hopefully that will also make it easier for Sphinx to showcase Markdown content in its documentation more prominently, and users will be able to naturally pick the markup language that best suits their needs, be it reST or MyST.

—

Considering using Read the Docs for your next Sphinx, Jupyter Book, or MkDocs project? Check out our documentation to get started!

Early 2021 talks and podcasts from Read the Docs

2021-07-06T00:00:00Z

During the first half of 2021 several team members of Read the Docs have talked about the company in podcasts and online events. If you want to learn more about our company directly from the people that are a core part of it, and hear our thoughts on other topics like open source sustainability and developer advocacy, this blog post is for you.

Eric @ Sustain podcast

Eric was the special guest of Sustain back in February, “a podcast about sustaining open source in the long haul”. Eric started by telling the story of how he and Anthony co-founded Read the Docs, talked about the Write the Docs community, described the challenges of launching EthicalAds in 2020, and discussed the opportunities of using ethical advertising to fund open source projects.

Listen to Eric online:

Juan Luis @ Data for Future podcast

Also in June, Juan Luis was invited for the second time to Data for Future, a podcast that seeks to “inspire positive actions towards an environmentally sustainable and socially just future through technology”. In an informal conversation, Juan Luis shared some numbers about the state of software documentation according to several surveys, promoted the Diátaxis documentation framework created by Daniele Procida, discussed his role as Developer Advocate at Read the Docs, and shared some possible opportunities for collaboration between Data Science practitioners and technical writers.

Listen to Juan Luis online:

Eric @ Upstream 2021 online conference

Read the Docs and EthicalAds supported Upstream 2021 in June, a one-day online event about “open source, the developers who use it, and the maintainers who make it”. Eric delivered a talk titled “Bootstrapping a sustainable open source project: The Read the Docs story”, in which he dived into some of the less known details of how Read the Docs was created, shared the different funding strategies the company attempted over the years, opened up about the dangers of burnout, and detailed the different commercial plans of Read the Docs as well as some thoughts about pricing schemes.

Watch Eric online:

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Read the Docs Blog - Posts tagged media