Enhancing our users’ documentation journey, one Sphinx extension at a time

Commercial documentation tools typically provide user preferences, system configurations, and easy access to key functionality that help users get the most out of product documentation. 

At Mattermost, we use Sphinx to develop and build our product documentation because we love supporting an open source documentation framework that’s so customizable and extendable. In addition to reStructuredText (rST) support, Sphinx also supports Markdown which keeps the learning curve low for content contributors.

While we love Sphinx, a standard Sphinx deployment doesn’t include some of the key features that we need out-of-the-box. We’ve learned how to install Sphinx extensions that enable new functionality across the entire Mattermost product documentation site.

We recently introduced three new documentation enhancements by incorporating three Sphinx extensions: 

• Copying and pasting code samples in a single click,
• Structuring product documentation content within selectable tabs, and
• Managing redirects for moved content. 

In this article, we’ll explain each extension, the value each offers, and how we use these extensions in Mattermost product documentation.

Getting started with Sphinx extensions

A great Sphinx extension is easy to install, continues to be supported over time, requires no additional configuration out-of-the-box to work, and supports branding customization.

Installing a Sphinx extension should only consist of a couple of quick steps:

1. At a terminal, in a local documentation development environment, install the Sphinx extension and regenerate the pipenv.lock file by running the following command: pipenv install sphinx-extension==version
2. Update Sphinx’s conf.py to add the extension in the extension section.

Without further ado, let’s dig into the specific extensions we use at Mattermost!

Copy & paste code samples

When you visit product documentation and find code samples that match the goal you’re trying to achieve, you likely want to try using those samples in your own test environment. Great page design includes copy and paste options for code examples to make trying out new code fast and easy.

For example, on the Deploy page of the Mattermost website, it’s easy to preview Mattermost functionality by copying and pasting a single line of code into a command line:

All code samples throughout the Mattermost Product Documentation should be as easy to access and apply as code samples on our website. Some documentation tools provide this functionality as a configuration setting or a user preference. Some sophisticated tools even let you control the look and feel of such an interface widget.

The sphinx-copybutton extension is one of a number of open source tools available from The Executable Book Project. It adds a copy/paste button to code blocks. We can overwrite any of the CSS rules, and the extension uses the clipboard.js library’s lightweight JavaScript code to power the widget. We’re using version 0.5.0 of this extension, released in February 2022.

Installing the sphinx-copybutton extension looked like this:

1. Run the following command: pipenv install sphinx-copybutton==0.5.0
2. Update Sphinx’s conf.py to add the extension in the extension section.

Tip: We strongly recommend getting into the practice of revisiting updates for extensions and dependencies at least twice a year, and to upgrade where needed. This ensures you’re benefiting from any code, feature, and security changes applied to extensions over time. You can also join the community online to stay informed of updates and changes year round. Some developers use update notifiers, RSS, and webhooks to get informed of new releases.

Once we installed the extension, the next time the documentation was built, every code block and code sample had a copy/paste widget added automatically. No manual work per code block was required.

Did this actually work the first time I tried it? 

No. Symlinks for python3 and pipenv in my local development environment weren’t configured correctly due to a recent macOS update. Once I re-added the symlinks, everything worked as expected.

Try it out yourself!

Learn how to deploy Mattermost for production use on Linux, from a tarball, using Kubernetes, or using Docker. Hover over any of the code blocks to copy the code in just one click. 

Structure user journeys with tabs

When you’re visiting software product documentation, you’re looking for a clear, golden path to success. As software complexity grows, the paths to success can become less straightforward and dependent on customer-determined variables like operating systems, databases, and product release versions. 

Organizing product documentation content in selectable tabs is an effective way to reduce clutter and reduce the amount of time readers spend looking for answers. Tabs can display more product information on a page without requiring the user to scroll through an entire page of content, and readers can reach relevant details with just a glance.

Mattermost features are released on Linux, Windows, and macOS. Mattermost self-hosted deployments support either MySQL or PostgreSQL databases. With this complexity in mind, Mattermost product documentation uses tabbed content to deliver guided success paths for installation, setup, and update workflows by Mattermost release, by platform, and by database.

The sphinx-tabs extension is another open source tool available from The Executable Book Project that enables us to structure and organize our product documentation content in tabs. We’re using version 3.2.0 of this extension, released in August 2021.

Installing the sphinx-tabs extension looked like this:

1. Run the following command: pipenv install sphinx-tabs==3.2.0
2. Update Sphinx’s conf.py to add the extension in the extension section.

Once the extension was installed, content authors can specify the following reStructuredText (RST) syntax to structure content in selectable tabs:

.. tabs::

	.. tab:: TabNameA

	Tab text goes here. This content displays by default when users visit this page.

	.. tab:: TabNameB

	Tab text goes here. The user must select this tab to see this content.

	.. tab:: TabNameC

	Tab text goes here. The user must select this tab to see this content

As long as text is nested (intended) and lines are spaced sufficiently in the source file, Sphinx draws and populates the interactive tabs when the product documentation is built. 

Within a given tab, most formatting syntax is supported, such as bullets and numbered steps, code samples, tables, and even notes. However, headings and subheadings aren’t supported, so we separate sections with bolded text instead. Tabs aren’t yet supported within the handful of Markdown source files we maintain.

Did this actually work the first time I tried it? 

No. The look and feel of the Mattermost Product Documentation site was originally defined by a Read The Docs Sphinx theme managed within a CSS file located in the root of our source directory. The extension wasn’t able to add its own CSS to that file until we renamed it and moved it where the extension was programmed to find it. 

Try it out yourself!

Learn how to install the Mattermost Desktop App on different Linux distributions, macOS, and Windows.

Automatically redirect users when pages move

Links to pages of the Mattermost Product Documentation exist in many places, including the internet, in browser bookmarks, in company emails, in blog entries, in user forum replies, and within the Mattermost product itself. 

When documentation pages move to another part of the documentation site, or when pages are archived, it’s important to ensure that users are directed to a new page location, otherwise, visitors see an error. 

Out-of-the-box, Sphinx doesn’t track or manage page redirects. The sphinx-reredirects extension is an open source tool available from Documatt that enables us to manage redirects for moved pages. We’re using version 0.0.1 of this extension released in April 2021.

A mapping is configured in the conf.py file for each redirected page consisting of old location to new location. Here’s an example of what redirects look like in the conf.py file:

redirects = {
  "about/deployments-and-editions.html": "https://docs.mattermost.com/about/editions-and-offerings.html",
  "administration/announcement-banner.html": "https://docs.mattermost.com/manage/announcement-banner.html",
  # more redirects here...
}

Installing the sphinx-reredirects extension looked like this:

1. Run the following command: pipenv install sphinx-reredirects==0.0.1
2. Update Sphinx’s conf.py to add the extension in the extension section.

Once the extension is installed, when the documentation is built, HTML files with redirects are written to the old page locations. When visitors attempt to access an outdated link that has a redirect defined, they’re automatically taken to the new page.

Did this actually work the first time I tried it? 

No. Functionally it worked; however, this extension didn’t account for newer releases of Sphinx featuring parallel build support. Initially, our local build times increased three-fold. Thanks to a Mattermost community member’s Docathon contribution, a Sphinx code change was added to enable parallel build support that greatly reduced build times overall.

Try it out yourself!

The Mattermost Important Upgrade Notes documentation has moved to a new home within the product documentation site. You used to go to https://docs.mattermost.com/administration/important-upgrade-notes.html to visit that page. When you click on that page today, you’re automatically taken to https://docs.mattermost.com/upgrade/important-upgrade-notes.html instead.

Extending our tool stack beyond its base functionality hasn’t been as easy as enabling a configuration option or a user preference. However, with help from our Mattermost Community, extending Sphinx has empowered us to deliver clearer, more straightforward guidance for users at every stage of their documentation journey. 

If you’re using Sphinx for your own documentation efforts, what extensions do you recommend we check out?

Want to get involved? 

We’re always looking for new opportunities to enhance the customer’s documentation experience through extensions to our tool stack.

We welcome your contributions, and getting started is easy!

Visit our DWG: Documentation Working Group Community channel to say hello, then head over to GitHub to browse our open help wanted tickets for Mattermost product documentation and developer documentation.