https://blog.readthedocs.comRead the Docs Blog - Posts tagged markdown2024-01-10T23:05:11.016488+00:00ABloghttps://blog.readthedocs.com/sphinx-markdown-2021/Sphinx and Markdown around the world in 20212021-12-20T00:00:00+00:00Juan Luis Cano Rodríguez<section id="sphinx-and-markdown-around-the-world-in-2021">
<p>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,
<a class="reference internal" href="../../../adding-markdown-support/"><span class="doc">we announced recommonmark</span></a>
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.)</p>
<p>It is no surprise that Markdown is in such demand:
thanks in large part to the huge popularity of GitHub,
<a class="reference external" href="https://passo.uno/docs-as-code-tools-open-standards/">Markdown is nowadays the most widely used markup language in open-source
projects</a>,
ahead of reStructuredText, the second in the list, by an order of magnitude.</p>
<p>This year, thanks to the CZI Grant we received last year
and the effort of other communities,
especially <a class="reference external" href="https://executablebooks.org">the Executable Book Project</a>,
we have devoted lots of resources to help consolidate Markdown
as a compelling markup language for Sphinx.</p>
<section id="writing-markdown-in-sphinx">
<h2>Writing Markdown in Sphinx</h2>
<p>To that end, we recognized the potential of MyST as a successor of recommonmark,
and <a class="reference internal" href="../../../newsletter-april-2021/"><span class="doc">deprecated the latter in favor of MyST-Parser</span></a>.
To <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/markdown.html" title="(in Sphinx v7.3.0)"><span class="xref std std-doc">start writing Markdown in Sphinx</span></a>,
you need to follow three steps:</p>
<ul class="simple">
<li><p>Install <code class="docutils literal notranslate"><span class="pre">MyST-Parser</span></code>: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">myst-parser</span></code></p></li>
<li><p>Add <code class="docutils literal notranslate"><span class="pre">myst_parser</span></code> to the list of Sphinx extensions:</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">extensions</span> <span class="o">=</span> <span class="p">[</span>
<span class="c1"># ...other extensions</span>
<span class="hll"> <span class="s2">"myst_parser"</span><span class="p">,</span>
</span><span class="p">]</span>
</pre></div>
</div>
<ul class="simple">
<li><p>Start writing content in <code class="docutils literal notranslate"><span class="pre">*.md</span></code> files!</p></li>
</ul>
<p>You can find more information in the <a class="reference external" href="https://myst-parser.readthedocs.io/en/v0.16.0/index.html" title="(in MyST Parser v0.16.0)"><span class="xref std std-doc">MyST-Parser documentation</span></a>.</p>
</section>
<section id="talks-and-workshops-at-conferences">
<h2>Talks and workshops at conferences</h2>
<p>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 <a class="footnote-reference brackets" href="#id2" id="id1">1</a>! Throughout 2021, we were present in several events:</p>
<ul class="simple">
<li><p>We conducted a networking session and a sprint about documentation
at <a class="reference external" href="https://www.scipy2021.scipy.org">SciPy US</a>,
and in that event we were kindly invited to
the <a class="reference external" href="https://www.eventbrite.com/e/sktime-doc-sprint-tickets-164990684579">sktime documentation sprint</a>.</p></li>
<li><p>We delivered a 90 minutes tutorial called
<a class="reference external" href="https://pydata.org/global2021/schedule/presentation/17/document-your-scientific-project-with-markdown-sphinx-and-read-the-docs/">“Document your scientific project with Markdown, Sphinx, and Read the
Docs”</a>
at PyData Global,
and we repeated a 120 minute version in Spanish language
at the <a class="reference external" href="https://conf.scipy.lat/en/">SciPy Latin America</a>.</p></li>
<li><p>And we also gave shorter talks at more broadly focused events:
<a class="reference external" href="https://www.pylatam.org/">PyCon Latam</a> and <a class="reference external" href="https://2021.es.pycon.org/">PyCon Spain</a>.</p></li>
</ul>
<p>We have generated workshop material that everybody is welcome to use:</p>
<ul class="simple">
<li><p>A <a class="reference external" href="https://github.com/readthedocs/tutorial-sphinx-markdown">main repository</a>
containing some introductory slides about Sphinx,
and detailed notes of every step of the tutorial.</p></li>
<li><p>A <a class="reference external" href="https://github.com/readthedocs/tutorial-sphinx-markdown-library/">supporting repository</a>
with a tiny Python library that gets used during the tutorial,
inspired by the one used in the <a class="reference external" href="https://www.sphinx-doc.org/en/master/tutorial/index.html" title="(in Sphinx v7.3.0)"><span class="xref std std-doc">official Sphinx tutorial</span></a>
we authored with the help of the Sphinx community.</p></li>
</ul>
<p>And finally, we have also developed an interactive web application to
<a class="reference external" href="https://mystyc.herokuapp.com/">translate small bits of reStructuredText to MyST Markdown</a>.</p>
<dl class="footnote brackets">
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><p>We also have submitted a proposal for SciPy India,
which was postponed to January 2022.
EuroSciPy and SciPy Japan didn’t happen in 2021.</p>
</dd>
</dl>
</section>
<section id="future-plans">
<h2>Future plans</h2>
<p>We are excited to see that the Executable Books team
has released <a class="reference external" href="https://pypi.org/project/myst-docutils/">myst-docutils</a>,
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.</p>
<p>—</p>
<p>Considering using Read the Docs for your next Sphinx, Jupyter Book, or MkDocs project?
Check out <a class="reference external" href="https://docs.readthedocs.io/">our documentation</a> to get started!</p>
</section>
</section>
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.2021-12-20T00:00:00+00:00