Read the Docs Blog - Posts tagged sphinx

Sphinx 4.4 release and other ecosystem news

2022-01-26T00:00:00Z

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 release

Sphinx 4.4 was released on January 17th with numerous changes, including:

Better control of intersphinx references with the :external: role

One of the power features of Sphinx is the ability to include cross references across projects, using intersphinx. 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 external role, coupled with the intersphinx_disabled_reftypes configuration introduced in Sphinx 4.3, enables documentation writers to control when intersphinx references should be used.

You can use the new :external: role as follows:

External reference: :external:py:class:`zipfile.ZipFile`.
External reference with constrained domain lookup: :external+python:py:class:`zipfile.ZipFile`.

See more information in the official documentation.

New asynchronous methods to load JavaScript files

The method sphinx.application.Sphinx.add_js_file() now accepts a new loading_method parameter that can either be "async" or "defer", which results in the script being loaded with the async or defer HTML attributes respectively.

Proper error messages when autosummary does not find a package

Sphinx ships the autosummary 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 ImportError.

You can read the complete Sphinx 4.4.0 release notes online.

Using Sphinx 4.4 on Read the Docs

Sphinx 4.4 is supported on Read the Docs. By default, RTD will install the latest version for you, as described in our documentation. If you are pinning your dependencies to improve the reproducibility of your builds, you can change the pinned version to sphinx==4.4.0 in either your requirements.txt or environment.yml.

Sphinx themes and extensions

Several other extensions and themes saw new releases recently, including:

pydata-sphinx-theme 0.8

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 the custom version switcher. As Chris Holdgraf summarizes in this Twitter thread, the new version brings other interesting additions, like better depth control of the left sidebar and custom SVG icons.

sphinx-codeautolink 0.9

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.

Demo of sphinx-codeautolink

sphinxcontrib-constdata 1.0

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:

Choose menu item :constdata:label:`menu.yaml?FileSaveAs`.

Upcoming

The Executable Books Project team is working on several exciting things around MyST, including the upcoming MyST-Parser 0.17 release and direct integration with Jupyter notebooks.

Preview of MyST integrated in Jupyter notebooks.

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.

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

Optimizing Sphinx Documentation for Search Engines

2019-08-29T00:00:00Z

Recently, we published a guide on SEO for technical docs with the goal of helping documentation authors and project maintainers create docs so that end users can find what they’re looking for easier.

One developer asked me point blank after I mentioned our new guide, “Hasn’t Google closed most of the loopholes that sites use to rank better?”. I’ve heard this opinion from a few technologists before so I wasn’t too surprised. Moz.com, an authority on search engine optimization, makes a distinction between what they call black hat SEO and white hat SEO to differentiate between these “loopholes” and more useful site improvements that help SEO.

Black hat SEO is basically a set of tactics some sites use to improve rankings without actually making their site better to end visitors. This includes techniques like displaying different content to search engines (cloaking), link farming, or adding semi-relevant keywords into a page (keyword stuffing). When Google and Bing discover a site doing this, they take action and lower a site’s ranking until the problems are fixed. Black hat SEO is inherently risky and we try to stay away from this kind of SEO.

Instead our guide focuses on white hat SEO which aims to improve your docs’ search engine rankings by helping search engine’s understand and index your docs better and present it better to searchers. This kind of SEO isn’t trying to cheat search engine rankings and it’s a win for everyone. Searchers find the content they’re looking for more easily while search engines understand the content better and can show more relevant results.

Specifically, we also tried to focus on SEO for documentation and how Sphinx and Read the Docs make it easier including:

Making your docs display better on search engine results
Helping search engines understand and index your docs better
Improving your ranking based on user and search engine feedback

Making your docs display better in search results

Google search engine results with the page title, URL, and a description.

Displaying more relevant information in search results will cause more people to click through to your docs. Again, your goal is not to use cheap tactics to rank better and trick users into clicking. Rather, you are trying to legitimately improve your content such that users better understand what to expect on a page before they click.

Some of the most important aspects of improved search listings are:

Use descriptive and accurate titles in the HTML <title> tag. With Sphinx, the <title> comes from the top heading on the page.
Ensure your URLs are descriptive. They are displayed in search results. For Sphinx, the URL uses the source file’s filename.
Make sure the words your readers would search for to find your site are actually included on your pages. Ideally, these key words should be in your <title> or description.

These concepts are not only important in helping guide users to click on your documentation, most of the same optimizations are useful to the search engine when indexing your site and when ranking your site for searchers.

Helping search engines understand your docs

Search engines like Google and Bing crawl through the internet following links and redirects in an attempt to understand and build an index of what various pages and sites are about.

These tips and features can help you control how search engines index your docs:

Make sure your entire site can be navigated by following links. If you have “orphan” pages, a search engine won’t find them. Using Sphinx’s “toctree” directive helps make sure all your pages are indexed and navigable.
Redirects and canonical URLs are useful when the same content exists in multiple places or moves from one page to another. Read the Docs dashboard lets authors setup redirects from one page to another or from one version of the documentation to another.
Using a robots.txt and sitemap.xml file can help you control how search engines crawl your docs. For example, you could tell search engines to ignore unsupported versions of your documentation. Read the Docs provides both a robots.txt and a sitemap and has ways for you to override them.

Improving your SEO ranking from feedback

Search engines provide tools to help webmasters build their site better and to give insights and feedback about the indexing of sites by the search engine spiders. Google Search Console and Bing Webmaster Tools are tools for webmasters to get feedback about the crawling of their sites (or docs in our case). These tools can show technical issues with indexing like pages that are failing for some reason and also possible security or spam issues on your site that can lower your ranking.

Google search console showing an issue with user generated spam, a constant battle at Read the Docs.

Feedback on keywords users use to find your docs is also really helpful. This is true both for the phrases people searched for on a search engine and for the search terms people queried in Sphinx and Read the Docs’ built-in search features. Analytics tools like Google Analytics can provide these insights, but as part of our search improvements and search analytics, Read the Docs is going to show project maintainers the most common search queries to help them improve as well.

SEO is no substitute for good writing

One area we didn’t detail in our guide is how more general improvements to technical writing can also improve your search engine rankings. This could be a whole post by itself.

Using simpler words, for example, has a number of advantages in technical writing. The excellent Microsoft Style Guide recommends using simple words and concise sentences and Apple’s Style Guide echoes the same sentiment. Simpler sentences are easier to understand for both people as well as machines like search engines and automatic translators.

While any style guide you read will tell you to avoid using jargon, technical writing and software docs have a certain amount of unavoidable technical terminology. Defining these terms and phrases when you first use them helps users as well as search engines.

In summary

Always keep in mind that your ultimate goal is to make your docs more discoverable by people, not machines. While the concepts and tactics here will help you rank better with search engines, providing high quality documentation and making it easier to find and understand is the best way to make sure people actually read the docs.

Adding Custom CSS or JavaScript to Sphinx Documentation

2019-07-10T00:00:00Z

In the Read the Docs documentation, we have a number of how-to guides to help people solve specific problems with Sphinx and Read the Docs. By far our most popular guide is on adding custom CSS and JavaScript to Sphinx.

In some older versions of Sphinx, this process was a little more challenging and it wasn’t as easy to figure out how to do it from the Sphinx docs. Sphinx 1.8 really streamlined this process especially for the simple cases.

Adding additional stylesheets or scripts

If your custom stylesheet is _static/css/custom.css, you can add that CSS file to the documentation using the Sphinx option html_css_files:

## conf.py

# These folders are copied to the documentation's HTML output
html_static_path = ['_static']

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
    'css/custom.css',
]

A similar approach can be used to add JavaScript files:

html_js_files = [
    'js/custom.js',
]

That’s it! You don’t need to create a Sphinx extension anymore to add a bit of custom CSS or JavaScript.

Customizations supported by your theme

I should also note that depending on the theme you’re using and what you’re hoping to accomplish, you may not even need to add custom CSS or JavaScript. Many themes support a number of “theme options” for customizing their look and feel without having to write custom code. For example, here are all the options for the Read the Docs theme and the Alabaster theme which are the two most popular themes on Read the Docs itself.

Both themes, for example, support the addition of Google Analytics to documentation by setting the analytics_id option:

## conf.py

html_theme_options = {
    'analytics_id': 'UA-XXXXXXX-1',  #  Provided in your GA dashboard
}

In summary

To recap, it only takes a few additions to your conf.py to add custom CSS or JavaScript. However, it’s also worth taking a look at your theme’s docs or Sphinx’s built-in HTML options to see if what you’re trying to do is already supported.

Happy documenting!