https://blog.readthedocs.com/archive/tag/theme/atom.xml 2021-08-23T00:00:00Z ABlog https://blog.readthedocs.com/theme-release-100rc1/ 2021-08-23T00:00:00Z 2021-08-23T00:00:00Z Anthony Johnson <div class="section" id="theme-release-1-0-0rc1"> <div class="admonition-update-version-1-0-0-has-been-released admonition"> <p class="first admonition-title">Update: Version 1.0.0 has been released!</p> <p>The 1.0.0 version of sphinx_rtd_theme was released Sept 13, 2021. You can install the latest version with:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip install <span class="s2">&quot;sphinx-rtd-theme~=1.0.0&quot;</span> </pre></div> </div> <p>Alternatively, you can upgrade the version installed using:</p> <div class="last highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip install --upgrade sphinx-rtd-theme </pre></div> </div> </div> <p>We are closing in on the next official release of <a class="reference external" href="https://github.com/readthedocs/sphinx_rtd_theme">sphinx_rtd_theme</a>, and we’re happy to announce that release candidate version 1.0.0rc1 was <a class="reference external" href="https://pypi.org/project/sphinx-rtd-theme/1.0.0rc1/">released to PyPI</a> last week! Project maintainers can contribute to the final release by <a class="reference internal" href="#testing">testing the release candidate</a> and raising any potential bugs on <a class="reference external" href="https://github.com/readthedocs/sphinx_rtd_theme/issues">our issue tracker</a>.</p> <p>Version 1.0.0 adds support for <a class="reference external" href="https://pypi.org/project/Sphinx/">Sphinx</a> 4, fixes several issues stemming from <a class="reference external" href="https://pypi.org/project/docutils/">docutils</a> 0.17, and contains several backwards-incompatible changes.</p> <div class="section" id="backwards-incompatible-changes"> <h2>Backwards incompatible changes</h2> <p>Users need to be aware of several backwards incompatible changes before upgrading:</p> <dl class="docutils"> <dt>Support dropped for old dependencies</dt><dd>Support is removed for Sphinx versions 1.6 or older, and for Python versions 3.0 to 3.3. Theme developers no longer test using these versions and compatibility is not guaranteed for these versions.</dd> <dt>HTML4 support will be removed</dt><dd>Support for the Sphinx HTML4 writer will be deprecated in release 2.0. A deprecation warning was added to alert users still using the HTML4 writer.</dd> <dt>Installation from source will be deprecated soon</dt><dd>Tentatively scheduled for release 3.0, installation from source will no longer be a supported installation method. Currently, users are installing directly from our GitHub repository, which complicates development of static assets. A deprecation warning was added to alert users of the upcoming change.</dd> </dl> </div> <div class="section" id="highlights"> <h2>Highlights</h2> <p>Here are some of the most significant additions included in release 1.0.0:</p> <dl class="docutils"> <dt>Support for new dependencies</dt><dd>The theme now supports Sphinx 4 and docutils 0.17, both the latest in each respective release series.</dd> <dt>New accessibility features</dt><dd>Also added were a number of accessibility updates, including better keyboard navigation support and more descriptive navigation for screen readers.</dd> <dt>Added 4 new translations</dt><dd>The theme is close to being almost fully translated in 14 different languages. This will provide project maintainers with localized navigation elements and accessibility content.</dd> </dl> <p><a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/en/latest/development.html#roadmap">The theme roadmap</a> has more information on upcoming releases, and backwards incompatible changes for each. A full list of changes included in this release is available in <a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/en/latest/changelog.html">the theme changelog</a>.</p> </div> <div class="section" id="testing"> <h2>Testing</h2> <p>The 1.0.0rc1 release is a pre-release package, meaning it will not install by default as the most recent release. Project maintainers will need to specify the release version explicitly to install the release candidate.</p> <p>In your package’s <code class="docutils literal notranslate"><span class="pre">extra_requirements</span></code>, or a separate <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code> file, you can pin this dependency with:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sphinx_rtd_theme</span><span class="o">~=</span><span class="mf">1.0.0</span><span class="n">rc1</span> </pre></div> </div> <p>If you notice any new, unwanted behavior, feel free to open an issue <a class="reference external" href="https://github.com/readthedocs/sphinx_rtd_theme/issues">on our issue tracker</a>.</p> </div> <div class="section" id="upcoming-changes"> <h2>Upcoming changes</h2> <p>We have several upcoming releases planned, covered in more depth in <a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/en/latest/development.html#roadmap">the theme roadmap</a>.</p> <p>Our next official release, currently targeted for October or November, will be version 1.1. This release will contain additional bug fixes and will be the last release supporting Sphinx versions less than 3.0. The next planed release will be version 2.0, in early 2022.</p> <p>The 2.0 release will be dropping support for a number of old dependencies, including Sphinx versions &lt; 3.0, Sphinx HTML4 writer support, and Internet Explorer 11.</p> <p>As the theme moves away from supporting direct installation through our GitHub repository, we want to preserve development previews of theme releases. In addition to several more focused releases on the theme roadmap, we will also be periodically publishing development releases to PyPI. This will be the prescribed method to use unreleased theme changes.</p> </div> <div class="section" id="thanks"> <h2>Thanks!</h2> <p>Special thanks to contributor <a class="reference external" href="https://github.com/Blendify">Blendify</a> for keeping up with support for fresh dependencies, and new contributor <a class="reference external" href="https://github.com/nienn">nienn</a> for helping with bug fixes and the heavy amount of testing required for this release!</p> </div> </div> https://blog.readthedocs.com/new-theme-read-the-docs/ 2013-11-04T00:00:00Z 2013-11-04T00:00:00Z Eric Holscher <div class="section" id="a-new-theme-for-read-the-docs"> <p>We have been <a class="reference external" href="https://github.com/rtfd/readthedocs.org/pulse/monthly">hard at work</a> improving <a class="reference external" href="http://readthedocs.org/">Read the Docs</a> over the past month. A large amount of back end work has been going on, and now we have a brand new documentation theme to showcase it.</p> <p>We have looked at how people use documentation, and built a beautiful and highly functional <a class="reference external" href="http://docs.readthedocs.org/en/latest/">new interface</a> for browsing documentation. We created a solution that looks great and works well.</p> <div class="section" id="creation"> <h2>Creation</h2> <p><a class="reference external" href="https://twitter.com/enemykite">Dave Snider</a> approached me about a month ago, interested in helping improve the documentation ecosystem. We talked about what could improve the Read the Docs experience for the greatest number of our users, and a new theme seemed like a great place to start.</p> </div> <div class="section" id="the-new-theme"> <h2>The New Theme</h2> <div class="section" id="full-site"> <h3>Full site</h3> <p>The full documentation page is now beautiful and streamlined. We got rid of the visual clutter and integrated a full-project Table of Contents in the sidebar. When you go into a specific page, a page-level contents get embedded in the sidebar as well. This allows you to keep context inside the documentation when you land on a page from a search.</p> <div class="section" id="old"> <h4>Old</h4> <a class="reference external image-reference" href="http://i.imgur.com/hWOnmKy.png"><img alt="http://i.imgur.com/hWOnmKy.png" src="http://i.imgur.com/hWOnmKy.png" style="width: 100%;" /></a> </div> <div class="section" id="new"> <h4>New</h4> <a class="reference external image-reference" href="http://i.imgur.com/7oLntvR.png"><img alt="http://i.imgur.com/7oLntvR.png" src="http://i.imgur.com/7oLntvR.png" style="width: 100%;" /></a> </div> </div> <div class="section" id="flyout"> <h3>Flyout</h3> <p>Read the Docs provides a lot of functionality for documentation projects. The flyout is the avenue to accessing that functionality. We need to pack all our functionality into this space.</p> <p>In the new theme, the flyout is integrated into the bottom left of the theme.</p> <div class="section" id="id1"> <h4>Old</h4> <div class="system-message"> <p class="system-message-title">System Message: INFO/1 (<tt class="docutils">/home/docs/checkouts/readthedocs.org/user_builds/goblog/checkouts/latest/new-theme-read-the-docs.rst</tt>, line 61); <em><a href="#id1">backlink</a></em></p> Duplicate implicit target name: “old”.</div> <p>The old flyout let you:</p> <blockquote> <div><ul class="simple"> <li>Change versions</li> <li>Go back to Read the Docs</li> </ul> </div></blockquote> <a class="reference external image-reference" href="http://i.imgur.com/CBDPzbD.png"><img alt="http://i.imgur.com/CBDPzbD.png" src="http://i.imgur.com/CBDPzbD.png" style="width: 50%;" /></a> </div> <div class="section" id="id2"> <h4>New</h4> <div class="system-message"> <p class="system-message-title">System Message: INFO/1 (<tt class="docutils">/home/docs/checkouts/readthedocs.org/user_builds/goblog/checkouts/latest/new-theme-read-the-docs.rst</tt>, line 73); <em><a href="#id2">backlink</a></em></p> Duplicate implicit target name: “new”.</div> <p>The new flyout lets you:</p> <blockquote> <div><ul class="simple"> <li>Change versions</li> <li>Go back to Read the Docs</li> <li>See the current version</li> <li>Show if the current version is out of date</li> <li>Download docs for offline viewing</li> <li>Contribute edits on GitHub or Bitbucket</li> <li>Do a full-text search (Coming soon)</li> </ul> </div></blockquote> <a class="reference external image-reference" href="http://i.imgur.com/9DRP8fj.png"><img alt="http://i.imgur.com/9DRP8fj.png" src="http://i.imgur.com/9DRP8fj.png" style="width: 50%;" /></a> </div> </div> <div class="section" id="mobile"> <h3>Mobile</h3> <p>The new theme really shines on mobile. We provide a beautiful interface for phones and tablets, while staying completely functional.</p> <a class="reference external image-reference" href="http://i.imgur.com/29uEpVs.png"><img alt="http://i.imgur.com/29uEpVs.png" src="http://i.imgur.com/29uEpVs.png" style="width: 100%;" /></a> </div> </div> <div class="section" id="using-it"> <h2>Using it</h2> <p>There are two ways that you can use this theme on Read the Docs. The first is to simply leave your <code class="docutils literal notranslate"><span class="pre">html_theme</span></code> variable set to <code class="docutils literal notranslate"><span class="pre">default</span></code>. This is now the default Read the Docs theme. You can also set <code class="docutils literal notranslate"><span class="pre">RTD_NEW_THEME</span> <span class="pre">=</span> <span class="pre">True</span></code> in your project’s <code class="docutils literal notranslate"><span class="pre">conf.py</span></code>, and we will use our theme when building on Read the Docs no matter what <code class="docutils literal notranslate"><span class="pre">html_theme</span></code> is set to.</p> <p>After you change these settings, simply rebuild your docs and the theme should update. More information about the theme can be found on the <a class="reference external" href="https://sphinx-rtd-theme.readthedocs.io/en/stable/">theme documentation page</a></p> <p>If you want to continue using the old theme, simply set <code class="docutils literal notranslate"><span class="pre">RTD_OLD_THEME</span> <span class="pre">=</span> <span class="pre">True</span></code> in your <code class="docutils literal notranslate"><span class="pre">conf.py</span></code>.</p> </div> <div class="section" id="conclusion"> <h2>Conclusion</h2> <p>This theme is a great addition to the documentation ecosystem. It is highly functional and beautiful, allowing users to easily navigate and find what they need.</p> <p>We have a few more tricks up our sleeves, but theme is ready to launch today. Over the next few weeks we’ll be adding a bit more functionality to it, which should be even more delightful.</p> <p>I hope that you enjoy using it. If you have any feedback, please <a class="reference external" href="http://github.com/snide/sphinx_rtd_theme/issues">open an issue</a> on GitHub. To follow announcements for Read the Docs, follow <a class="reference external" href="http://twitter.com/readthedocs">us on Twitter</a>.</p> <p>If you want to support work like this, help <a class="reference external" href="https://www.gittip.com/readthedocs/">fund development on Read the Docs</a> on Gittip.</p> </div> </div>