Thoughts on using Sphinx and Read the Docs for documenting my next project

Let’s sphinx it….

Image from https://read-the-docs-guidelines.readthedocs-hosted.com/branding.html

What is Sphinx

Sphinx is the documentation tool that provides a robust and mature solution for software documentation. It includes a number of features that writers expect, such as:

• Single-Source Publishing
• Many mature HTML themes and responsiveness so a great user experience.
• Referencing across pages, documents, and projects
• Indexing and Internationalization support
• Sematic referencing of software concepts, code comments
• Support for documenting HTTP APIs, extensions with the Python language
• Custom builders like linkchecker, XML builder, JSON builder, etc...
• Mainly a vast variety of third-party extensions

and so on……

If you are already familiar with Sphinx you probably know about “Read the Docs”. For people who don’t know what it is.

Read the Docs!

Read the Docs is a hosting platform for Sphinx-generated documentation. It builds on top of the Sphinx to provide hosting for Sphinx documentation that keeps your docs up to date across versions. Together, they are a wonderful set of tools that developers and technical writers both enjoy using.

Here are some of the features that Read the Docs support:

• Version Control — Can be linked with any famous repository hosting system
• Index the documentation to allow full-text-search
• Custom Domain hosting, Also host multiple versions using tags and branches in your repository
• Webhooks support, etc…

Example Projects using Sphinx & Read the Docs:

• ASP.NET — Microsoft’s web framework: https://docs.asp.net
• Julia — A language for scientific computing: http://docs.julialang.org
• Jupyter — An interactive programming environment: http://jupyter.readthedocs.io
• PHPMyAdmin — A web-based database editor: https://docs.phpmyadmin.net
• Write the Docs — The community site for Write the Docs — http://www.writethedocs.org

Take on Sphinx & Read the Docs:

The more integrated with the product development process technical writers get, the better our products get. Tools that integrate documentation and development workflows make it much easier for writers to become part of the larger development process.

Sphinx and Read the Docs have been battle-tested by hundreds of thousands of open source developers for years, and are a great choice for any software documentation project.

Personal Intro:

Maybe this is too late but might need to get a better understanding of the next sections you are going to read, Okiee this time I'm not starting from my Name ;)

Eswar Vandanapu & I are working together for 7+ years with multiple organizations. Most of those organizations using sphinx for their products documentation. Actually, they use different products just for documentation Example: Atlassian, Sphinx, Word Docs, etc…

Problems we face most of the time:

• Integrating graphs/canvas content example draw.io is a bit hard earlier — But now anymore using this extension (Created by Eswar Vandanapu). With this now we can add the drawio-html directive to include draw.io diagrams into the generated HTML documentation.
• The other important problem we face on daily basis is reviewing the documentation.

Thoughts on Having Reviews / Comments support for Sphinx Documentation:

Usually, the Document/Content writer writes the product documentation based on the inputs provided by the Product Manager, Engineering Manager, and their own experience/understanding of the product.

So before handovering product documentation/release notes to customers, it needs to go through multiple iterations to review it by PM, Engineering Manager, Document Writer, others…

For the review purposes in all these iterations, we understand people generally create multiple Word Docs so they can add their comments and get it resolved. For Atlassian sometimes so they can directly share it some of the friendly customers. Likewise for every major release or product people create multiple versions of a single document just for reviewing.

So, We are thinking of having an extension or support in sphinx where people can directly review and add comments to the documentation so they people can discuss the point and do the necessary changes right there in the Sphinx / Read the Docs itself and publish it to the public once everyone is agreed.

This extension should also be able to handle authentication & authorization so it can only be accessible by specific people in the org, only people who have the authorization to make the changes should do it.

This way it helps people who involve in the product documentation can save so much time and effort and organizations can save the cost and resources.

So we think it will be a great add-on to Sphinx & Read the Docs.

What do you think?

Please help us understand the need and use of it by liking and commenting on this, also post us if you have anything that you think Sphinx / Read the Docs should support in the future.

Note: Please don’t copy the idea, You may get into copyright issues ;)

—

Thanks

BMS.