Skip to content

Latest commit

 

History

History
38 lines (25 loc) · 3.19 KB

recommendations.md

File metadata and controls

38 lines (25 loc) · 3.19 KB

Recommendations

This page lists a few opinionated recommendations for Sphinx plugins to use in your documentation along with Furo. All these plugins work well with Furo-based Sphinx documentation, but they are not inherently tied to Furo.

MyST (Markedly Structured Text) : This project enables writing documentation with Markdown in Sphinx1. This is achieved by making well-thought-out extensions to the CommonMark Specification, which make it as capable as reStructuredText. In case you're wondering if that works well... this documentation is written using MyST.

Markdown is a significantly more popular markup format than reStructuredText. This means that it's likely that potential contributors/developers on the project are significantly more familiar with Markdown than reStructuredText. MyST gives you the best of both worlds -- simplicity and familiarity of Markdown with the extensibility power of reST.

sphinxext-opengraph : This project automagically adds Open Graph meta tags to your site's generated HTML. The Open Graph protocol is used by social media websites to determine how to present a page when a link is posted, and by search engines as a criterion toward ranking.

sphinx-inline-tabs : This project provides a straightforward way to introduce tabbed content within your documentation. This is useful for instructions specific to something about the end user (like their OS, or preferred language, etc). This is a great way to organise complex bits of documentation without major trouble.

Disclaimer: I am the creator and the primary maintainer of sphinx-inline-tabs.

sphinx-autobuild : This project provides a live-reloading server, that rebuilds the documentation and refreshes any open pages automatically when changes are saved. This enables a much shorter feedback loop which can help boost productivity when writing documentation. Furo's development workflow is based on uses this project.

Disclaimer: I am the primary maintainer of sphinx-autobuild.

sphinx-copybutton : This project adds a convenient copy button to code blocks. This is a subtle but effective user experience improvement when there are code snippets that a user might wish to copy from (examples, sample code etc).

In addition to the above, a shoutout to the Executable Books project which maintains many useful Sphinx extensions including some listed above.

Footnotes

  1. MyST addresses all the concerns that have been raised when arguing against Using Markdown for Technical Documentation, which really only leaves us with the good bits. :)