https://blog.readthedocs.comRead the Docs Blog - Posts from Madrid, Spain2024-01-10T23:05:10.547656+00:00ABloghttps://blog.readthedocs.com/sphinx-4-4-release-other-ecosystem-news/Sphinx 4.4 release and other ecosystem news2022-01-26T00:00:00+00:00Juan Luis Cano RodrÃguez<section id="sphinx-4-4-release-and-other-ecosystem-news">
<p>In this post we spread the word about
the most relevant news of the Sphinx ecosystem of the past weeks,
including Sphinx itself as well as extensions and themes developed by the community.</p>
<section id="sphinx-4-4-release">
<h2>Sphinx 4.4 release</h2>
<p><strong>Sphinx 4.4</strong> was released on January 17th with numerous changes, including:</p>
<dl>
<dt>Better control of intersphinx references with the <code class="docutils literal notranslate"><span class="pre">:external:</span></code> role</dt><dd><p>One of the power features of Sphinx is the ability to include
cross references across projects, using <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html" title="(in Sphinx v7.3.0)"><span class="xref std std-doc">intersphinx</span></a>.
By default, Sphinx transparently attempts to locate objects in external projects
if they are not found in the current one,
which is useful but also can become confusing in some cases.
The new <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#role-external" title="(in Sphinx v7.3.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">external</span></code></a> role, coupled with the
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes">intersphinx_disabled_reftypes</a>
configuration introduced in Sphinx 4.3,
enables documentation writers to control
when intersphinx references should be used.</p>
<p>You can use the new <code class="docutils literal notranslate"><span class="pre">:external:</span></code> role as follows:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>External reference: <span class="na">:external:py:class:</span><span class="nv">`zipfile.ZipFile`</span>.
External reference with constrained domain lookup: :external+python<span class="na">:py:class:</span><span class="nv">`zipfile.ZipFile`</span>.
</pre></div>
</div>
<p>See more information in <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#role-external" title="(in Sphinx v7.3.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">the</span> <span class="pre">official</span> <span class="pre">documentation</span></code></a>.</p>
</dd>
<dt>New asynchronous methods to load JavaScript files</dt><dd><p>The method <a class="reference external" href="https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file" title="(in Sphinx v7.3.0)"><code class="docutils literal notranslate"><span class="pre">sphinx.application.Sphinx.add_js_file()</span></code></a>
now accepts a new <code class="docutils literal notranslate"><span class="pre">loading_method</span></code> parameter that can either be <code class="docutils literal notranslate"><span class="pre">"async"</span></code> or <code class="docutils literal notranslate"><span class="pre">"defer"</span></code>,
which results in the script being loaded with the
<a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-async">async</a> or
<a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer">defer</a>
HTML attributes respectively.</p>
</dd>
<dt>Proper error messages when autosummary does not find a package</dt><dd><p>Sphinx ships the <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html" title="(in Sphinx v7.3.0)"><span class="xref std std-doc">autosummary</span></a> extension
to automatically generate API pages of a Python library.
However, autosummary used to raise misleading error messages if the target library failed to import,
which resulted in user frustration.
This problem has now been fixed and autosummary properly points out the reason of the <code class="docutils literal notranslate"><span class="pre">ImportError</span></code>.</p>
</dd>
</dl>
<p>You can read the <a class="reference external" href="https://www.sphinx-doc.org/en/master/changes.html#release-4-4-0-released-jan-17-2022">complete Sphinx 4.4.0 release
notes</a> online.</p>
<section id="using-sphinx-4-4-on-read-the-docs">
<h3>Using Sphinx 4.4 on Read the Docs</h3>
<p>Sphinx 4.4 is supported on Read the Docs. By default, RTD will install the latest version for you,
as described in <a class="reference external" href="https://docs.readthedocs.io/en/stable/build-default-versions.html#external-dependencies" title="(in Read the Docs user documentation v10.15.0)"><span class="xref std std-ref">our documentation</span></a>.
If you are <a class="reference external" href="https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html" title="(in Read the Docs user documentation v10.15.0)"><span class="xref std std-doc">pinning your dependencies</span></a>
to improve the reproducibility of your builds,
you can change the pinned version to <code class="docutils literal notranslate"><span class="pre">sphinx==4.4.0</span></code>
in either your <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code> or <code class="docutils literal notranslate"><span class="pre">environment.yml</span></code>.</p>
</section>
</section>
<section id="sphinx-themes-and-extensions">
<h2>Sphinx themes and extensions</h2>
<p>Several other extensions and themes saw new releases recently, including:</p>
<dl>
<dt><a class="reference external" href="https://github.com/pydata/pydata-sphinx-theme/releases/tag/v0.8.0">pydata-sphinx-theme 0.8</a></dt><dd><p>pydata-sphinx-theme is a Sphinx theme based on Bootstrap CSS developed by the PyData community,
The Read the Docs team collaborated with the developers
to make some of the new features of 0.8 behave correctly in our platform, in particular
<a class="reference external" href="https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#add-a-dropdown-to-switch-between-docs-versions">the custom version
switcher</a>.
As <a class="reference external" href="https://twitter.com/choldgraf/status/1482435411301449729">Chris Holdgraf summarizes in this Twitter
thread</a>,
the new version brings other interesting additions,
like <a class="reference external" href="https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#navigation-depth-and-collapsing-of-the-sidebar">better depth control of the left
sidebar</a>
and <a class="reference external" href="https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#local-image-icons">custom SVG
icons</a>.</p>
</dd>
<dt><a class="reference external" href="https://sphinx-codeautolink.readthedocs.io/en/stable/release_notes.html#id2">sphinx-codeautolink 0.9</a></dt><dd><p>sphinx-codeautolink is a Sphinx extension to automatically include links inside code blocks.
The 0.9 version now links Python builtin objects if intersphinx is properly configured
and has several logging improvements.</p>
<figure class="align-center" id="id1">
<img alt="Demo of sphinx-codeautolink" src="../../../_images/sphinx-codeautolink.gif" />
<figcaption>
<p><span class="caption-text">Demo of sphinx-codeautolink</span></p>
</figcaption>
</figure>
</dd>
<dt><a class="reference external" href="https://documatt.gitlab.io/sphinxcontrib-constdata/">sphinxcontrib-constdata 1.0</a></dt><dd><p>sphinxcontrib-constadata is a new Sphinx extension that allows documentation writers to
easily load data stored in CSV, JSON, and YAML files.
For example, it can be used to load UI labels (button labels, menu selection labels)
from external files instead of hardcoding them in the documentation for better maintenance,
for example:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Choose menu item <span class="na">:constdata:label:</span><span class="nv">`menu.yaml?FileSaveAs`</span>.
</pre></div>
</div>
</dd>
</dl>
</section>
<section id="upcoming">
<h2>Upcoming</h2>
<p>The Executable Books Project team is working on several exciting things around MyST,
including <a class="reference external" href="https://github.com/executablebooks/MyST-Parser/pull/507">the upcoming MyST-Parser 0.17 release</a>
and <a class="reference external" href="https://twitter.com/choldgraf/status/1485666900784730112">direct integration with Jupyter notebooks</a>.</p>
<figure class="align-center" id="id2">
<img alt="Preview of MyST integrated in Jupyter notebooks." src="../../../_images/jupyter-myst.gif" />
<figcaption>
<p><span class="caption-text">Preview of MyST integrated in Jupyter notebooks.</span></p>
</figcaption>
</figure>
<p>We are excited about seeing new and old Sphinx extensions being developed by the community,
and we thank the Sphinx maintainers for their excellent work.</p>
<hr class="docutils" />
<p>Considering using Read the Docs for your next Sphinx?
Check out <a class="reference external" href="https://docs.readthedocs.io/">our documentation</a> to get started!</p>
</section>
</section>
In this post we spread the word about
the most relevant news of the Sphinx ecosystem of the past weeks,
including Sphinx itself as well as extensions and themes developed by the community.Sphinx 4.4 was released on January 17th with numerous changes, including:2022-01-26T00:00:00+00:00