http://ericholscher.comEric Holscher - Posts tagged article2024-02-28T16:22:28.786942+00:00ABloghttp://ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/An introduction to Sphinx and Read the Docs for Technical Writers2016-07-01T00:00:00+00:00<section id="an-introduction-to-sphinx-and-read-the-docs-for-technical-writers">
<p>Treating documentation as code is becoming a major theme in the software industry.
This is coming from both sides,
with developers starting to treat documentation as a priority alongside tests and code,
and writers seeing a lot of value in integrating more into the development process.
This marrying of cultures isn’t simple,
but having the proper tools for the job makes both sides happy with the process and the results that get produced.</p>
<p>A lot of developer tools don’t work well for writers.
Sphinx and Read the Docs are unique in this ecosystem,
in that they have powerful features that both writers and developers want,
in one convenient package.</p>
<section id="overview-of-the-ecosystem">
<h2>Overview of the Ecosystem</h2>
<p>Read the Docs is the largest open source documentation hosting site in the world.
Open Source in this context means both that the code is open source,
and the documentation hosted is for open source software.
It is a developer focused platform,
but it has most of the features that technical writers have come to expect in a tool as well.
This blending of worlds makes it the best suited platform for teams that want both writers and developers contributing to product and API documentation.</p>
<p>Read the Docs is best thought of as a continuous documentation platform for Sphinx.
Continuous documentation is analogous to continuous integration of code,
which runs the tests on each commit.
In practice it means that your documentation is built,
tested,
and updated on every commit.</p>
<p>Sphinx provides a documentation generator that is best-in-class for software docs.
Sphinx documents are written in the reStructuredText markup language.
reStructuredText is similar to Markdown,
but much more powerful,
as you’ll see in this article.
Read the Docs provides a hosting platform for Sphinx,
running a build on each commit of your repository.</p>
<p>As a writer who uses Sphinx,
your day to day is writing reStructuredText in plain text files.
You then build your documentation by running Sphinx on the command line.
Generally it’s easiest to output HTML for local writing and testing,
and then you can let Read the Docs generate PDF’s and other formats.</p>
<p>This article provides an overview of the features of Sphinx and Read the Docs,
and enables you to evaluate them for use in your organization.</p>
</section>
<section id="introduction-to-sphinx">
<h2>Introduction to Sphinx</h2>
<p><a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a> is the documentation tool of choice for the Python language community,
and increasingly also for other programming languages and tools.
It was <a class="reference external" href="https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)">originally created</a> in 2008 to document the Python language itself.</p>
<p>Over the past eight years,
it has turned into a robust and mature solution for software documentation.
It includes a number of features that writers expect,
such as:</p>
<ul class="simple">
<li><dl class="simple">
<dt>Single Source Publishing</dt><dd><ul>
<li><p>Output HTML, PDF, ePub, and more</p></li>
<li><p>Content reuse through includes</p></li>
<li><p>Conditional includes based on content type and tags</p></li>
</ul>
</dd>
</dl>
</li>
<li><p>Multiple mature HTML themes that provide great user experience on mobile and desktop</p></li>
<li><p>Referencing across pages, documents, and projects</p></li>
<li><p>Index and Glossary support</p></li>
<li><p>Internationalization support</p></li>
</ul>
<p>It also has practical and powerful tools for documenting software specifically,
including:</p>
<ul class="simple">
<li><p>Semantic referencing of software concepts, including classes, functions, programs, variables, etc.</p></li>
<li><p>Including code comments in documentation output for many programming languages</p></li>
<li><p>Tools for documenting HTTP APIs</p></li>
<li><p>Extensions with the Python language</p></li>
<li><p>A vast array of third party extensions providing powerful new roles and directives</p></li>
</ul>
<p>This article isn’t large enough to cover all of the power packed into this tool.
But I hope to show enough to pique reader interest so that you can try these tools out and research their capacity for yourself.</p>
<section id="using-sphinx">
<h3>Using Sphinx</h3>
<p>reStructuredText is a powerful language primarily because the syntax can be extended.
reStructuredText supports two types of extension:</p>
<ul class="simple">
<li><p>Paragraph level (with Directives)</p></li>
<li><p>Inline level (with Interpreted Text Roles, or roles for short)</p></li>
</ul>
<section id="paragraph-level-markup">
<h4>Paragraph Level Markup</h4>
<p>Let’s see a basic example of a <em>Directive</em> in reStructuredText:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>.. warning:: Here be dragons! This topic covers a number of options that
might alter your database.
Proceed with caution!
.. figure:: screenshot-control-panel.jpg
:width: 50%
An overview of the admin control panel.
</pre></div>
</div>
<p>Here <code class="docutils literal notranslate"><span class="pre">warning</span></code> acts as the name of the directive,
and is the part you can extend for custom directives.
In the <code class="docutils literal notranslate"><span class="pre">figure</span></code>,
<code class="docutils literal notranslate"><span class="pre">screenshot-control-panel.jpg</span></code> is an <em>argument</em>,
<code class="docutils literal notranslate"><span class="pre">:width:</span></code> is an <em>option</em>,
and the rest is the <em>content</em>
They enable customization of directives,
and show the full power of reStructuredText.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You’ll notice that Sphinx uses whitespace to denote where a directive ends.
The “Proceed with caution!” is still part of the <code class="docutils literal notranslate"><span class="pre">warning</span></code>,
and everything that continues to be indented will be part of that warning.</p>
</div>
<p>Sphinx ships with a number of powerful directives for documenting code.
You can also write your own if you have someone on your team that knows Python.</p>
</section>
<section id="inline-markup">
<h4>Inline Markup</h4>
<p>For extensibility inside of a paragraph Sphinx uses roles.
Here is an example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>You can learn more about this in :rfc:`1984`.
It is implemented in our code at :class:`System.Security`
</pre></div>
</div>
<p>Here you can see <code class="docutils literal notranslate"><span class="pre">rfc</span></code> and <code class="docutils literal notranslate"><span class="pre">class</span></code> act as the name of the role,
and then you can pass in a single argument.
For the <code class="docutils literal notranslate"><span class="pre">rfc</span></code> role,
it generates a link to the online reference for RFC 1984 with a text of <code class="docutils literal notranslate"><span class="pre">RFC</span> <span class="pre">1984</span></code>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">class</span></code> role is where things get interesting.
This acts as a reference to the class <code class="docutils literal notranslate"><span class="pre">System.Security</span></code> that is documented in your project,
which is a hyperlink in the HTML output,
but also a working link in PDF and other outputs as well.</p>
<p>You can implement your own roles with Python.
This enables you to create powerful semantic constructs inside the actual <em>markup</em> you’re using to write documentation.
If you worked building software at a toy factory,
you can create a custom semantic sytnax for our own software:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Check out :jira:`199` for information on the :toy:`jump-rope`.
There is a fix in our :unit-test:`assert-jump-rope-length`.
</pre></div>
</div>
<p>These custom roles work in your <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files,
but also in any kind content that is pulled out of a comment in your source code too.</p>
<p>Now,
let’s see how you take these sets of reStructuredText files and turn them into a document set.</p>
</section>
</section>
</section>
<section id="table-of-contents-tree">
<h2>Table of Contents Tree</h2>
<p>Sphinx lets you combine multiple pages into a cohesive hierarchy.
The <code class="docutils literal notranslate"><span class="pre">toctree</span></code> directive is a fundamental part of this structure.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">toctree</span><span class="p">::</span>
<span class="nc">:maxdepth:</span> 2
install
support
</pre></div>
</div>
<p>The above example outputs a Table of Contents in the page where it occurs.
The <code class="docutils literal notranslate"><span class="pre">maxdepth</span></code> argument tells Sphinx to include 2 levels of headers.
This also tells Sphinx that the other pages are sub-pages of the current page,
creating a “tree” structure of the pages:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>index
├── install
├── support
</pre></div>
</div>
<p>The TOC Tree is also used for generating the global navigation inside of Sphinx.
The <cite>index</cite> at the top of your project acts as the root of the navigation.
The <code class="docutils literal notranslate"><span class="pre">toctree</span></code> is quite important,
and one of the most powerful concepts in Sphinx.</p>
<p>More info on the <code class="docutils literal notranslate"><span class="pre">toctree</span></code> can be found here:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/toctree.html">http://www.sphinx-doc.org/en/stable/markup/toctree.html</a></p></li>
</ul>
</section>
<section id="working-with-code">
<h2>Working with Code</h2>
<p>Showing code examples is a common task in all documentation.
Sphinx is quite well prepared for this task.
Let’s see how we can show a basic code example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">code</span><span class="o">-</span><span class="n">block</span><span class="p">::</span> <span class="n">python</span>
<span class="p">:</span><span class="n">linenos</span><span class="p">:</span>
<span class="kn">import</span> <span class="nn">antigravity</span>
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
<span class="n">antigravity</span><span class="o">.</span><span class="n">fly</span><span class="p">()</span>
</pre></div>
</div>
<p>This markup displays the Python snippet with syntax highlighting and line numbers.
The <code class="docutils literal notranslate"><span class="pre">python</span></code> in the above example is an argument to the <code class="docutils literal notranslate"><span class="pre">code-block</span></code> <em>directive</em>.
The <code class="docutils literal notranslate"><span class="pre">:linesnos:</span></code> is an <em>option</em> that says to display line numbers for the code block.
In the HTML output,
it would look like this:</p>
<img alt="../../../../_images/code.png" src="../../../../_images/code.png" />
<p>Sphinx doesn’t stop there though.
It allows you to store your code examples in external files,
and be included in your documentation for easier maintenance.
This uses the <code class="docutils literal notranslate"><span class="pre">literalinclude</span></code> directive:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">literalinclude</span><span class="p">::</span> <span class="n">example</span><span class="o">.</span><span class="n">rb</span>
<span class="p">:</span><span class="n">language</span><span class="p">:</span> <span class="n">ruby</span>
<span class="p">:</span><span class="n">emphasize</span><span class="o">-</span><span class="n">lines</span><span class="p">:</span> <span class="mi">12</span><span class="p">,</span><span class="mi">15</span><span class="o">-</span><span class="mi">18</span>
</pre></div>
</div>
<p>The neat addition here is the <code class="docutils literal notranslate"><span class="pre">:emphasize-lines:</span></code>.
This shows the lines highlighted in your output.
This is quite useful for showing sets of code examples where a subset of the code changes.
You can also specify just a subset of lines to show with the <code class="docutils literal notranslate"><span class="pre">:lines:</span></code> option,
so you don’t have to manage multiple snippets.</p>
<p>There’s far more power to Sphinx directives than this article can show.
You can see the full documentation for them on the Sphinx website:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/code.html">http://www.sphinx-doc.org/en/stable/markup/code.html</a></p></li>
</ul>
</section>
<section id="working-with-references">
<h2>Working with References</h2>
<p>A powerful reference system is a large part of the power of Sphinx.
You are able to reference arbitrary headings and paragraphs in your content,
but also semantically reference a large number of programming concepts as well.
On top of that,
Sphinx includes <code class="docutils literal notranslate"><span class="pre">intersphinx</span></code> which allows referencing across Sphinx projects.
This means that if you have multiple projects inside your company,
you can still use semantic referencing across them!</p>
<p>A simple reference is defined like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>.. _reference-target-name::
This is a bit of content.
This is how you point to the above reference, :ref:`reference-target-name`
</pre></div>
</div>
<p>Sphinx also includes a number of other semantic reference types.
Examples of other semantic reference types that Sphinx provides:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">:doc:</span></code> for referencing documents</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">:cls:</span></code> for referencing programming classes</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">:term:</span></code> for referencing glossary terms</p></li>
</ul>
<p>All references support <code class="docutils literal notranslate"><span class="pre">intersphinx</span></code>,
which allows you to prefix your references with a specific project name.
So if your user guide needs to reference your API documentation,
you could do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Check out the :cls:`api-ref:api.request`
</pre></div>
</div>
<p>Which would know to look in your <code class="docutils literal notranslate"><span class="pre">api-ref</span></code> project for the class.
The name <code class="docutils literal notranslate"><span class="pre">api-ref</span></code> is arbitrary,
and is defined in your project configuration’s <code class="docutils literal notranslate"><span class="pre">intersphinx_mapping</span></code>.</p>
<p>You see the complete set of references in the Sphinx documentation:</p>
<ul class="simple">
<li><p>Cross Referencing Syntax - <a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-syntax">http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-syntax</a></p></li>
<li><p>Intersphinx - <a class="reference external" href="http://www.sphinx-doc.org/en/stable/ext/intersphinx.html">http://www.sphinx-doc.org/en/stable/ext/intersphinx.html</a></p></li>
</ul>
</section>
<section id="including-comments-form-source-code">
<h2>Including comments form source code</h2>
<p>Integration with code is one of the largest benefits of Sphinx.
You can easily embed software comments from multiple languages,
including Python, Java, and .NET.</p>
<p>Here is an example of embedding Python documentation for a class in your project:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Make a request
--------------
You can make requests using the :func:`api.request` module.
It makes HTTP requests against our website.
Here is the basic function signature:
.. autofunction:: api.request
</pre></div>
</div>
<p>As you can see,
you can include generated content in the file that you’re writing by hand.
This allows for building a narrative around generated code comments,
instead of giving your users a separate User Guide and API Reference,
which is often times just an alphabetical listing of code!</p>
<p>Documentation is best written by humans.
Pulling comments from source code is valuable,
but it should be a small part of a proper set of documentation.</p>
<p>You can read more about including code comments in the following documentation pages:</p>
<ul class="simple">
<li><p>Domains, where the references are defined - <a class="reference external" href="http://www.sphinx-doc.org/en/stable/domains.html#what-is-a-domain">http://www.sphinx-doc.org/en/stable/domains.html#what-is-a-domain</a></p></li>
<li><p>Autodoc, which generates docs from Python code - <a class="reference external" href="http://www.sphinx-doc.org/en/stable/ext/autodoc.html">http://www.sphinx-doc.org/en/stable/ext/autodoc.html</a></p></li>
<li><p>Breathe, which bridges doxygen and Sphinx - <a class="reference external" href="https://breathe.readthedocs.io/en/latest/">https://breathe.readthedocs.io/en/latest/</a></p></li>
<li><p>AutoAPI, which bridges .NET and Sphinx - <a class="reference external" href="https://sphinx-autoapi.readthedocs.io/en/latest/">https://sphinx-autoapi.readthedocs.io/en/latest/</a></p></li>
</ul>
</section>
<section id="tables">
<h2>Tables</h2>
<p>Working with tables can be the bane of anyone who uses plaintext markup languages.
Most other languages require that you write them in the file with some arcane syntax.
However with reStructuredText,
you can use directives to make this much easier.</p>
<p>You can use either of two powerful list directives,
<code class="docutils literal notranslate"><span class="pre">csv-table</span></code> and <code class="docutils literal notranslate"><span class="pre">list-table</span></code>.
Here is an example of <code class="docutils literal notranslate"><span class="pre">csv-table</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Popcorn", 1.99, "Straight from the oven"
</pre></div>
</div>
<p>This shows the inline markup,
however the CSV can also be managed in an external file.
This allows you to manage your complex tables in a third party tool,
and have your documentation consume them from a CSV which is a much nicer workflow.</p>
</section>
<section id="internationalization">
<h2>Internationalization</h2>
<p>Sphinx includes support for translating documentation into multiple languages.
Since sphinx knows the structure of your documents,
it is able to generate a translatable strings split by each paragraph, heading, or figure.</p>
<p>Sphinx internationalization works using the <em>gettext</em> system.
It ships with a builder that allows you to generate a catalog:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">gettext</span>
</pre></div>
</div>
<p>You can then use that catalog as the base translation,
using any tool that supports gettext.
I recommend using Transifex,
which gives you a web-based system for translating the documentation:</p>
<img alt="../../../../_images/transifex.png" src="../../../../_images/transifex.png" />
<p>You can then tell Sphinx what language to generate for its documentation when you build it by setting the <code class="docutils literal notranslate"><span class="pre">language</span></code> setting.
Read the Docs also supports internationalization,
allowing you to host multiple languages of your project documentation.</p>
<p>More information on Sphinx internationalization can be found here:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www.sphinx-doc.org/en/stable/intl.html">http://www.sphinx-doc.org/en/stable/intl.html</a></p></li>
<li><p><a class="reference external" href="http://docs.readthedocs.io/en/latest/localization.html">http://docs.readthedocs.io/en/latest/localization.html</a></p></li>
</ul>
</section>
<section id="my-blog">
<h2>My blog</h2>
<p>Sphinx is quite versatile,
which means you can use it for a lot of different use cases.
I use a package called <code class="docutils literal notranslate"><span class="pre">ablog</span></code> for hosting of my blog over at <a class="reference external" href="http://ericholscher.com">http://ericholscher.com</a>.</p>
<p>The most basic usage allows you to specify that a document is a blog post with the <code class="docutils literal notranslate"><span class="pre">post</span></code> directive:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">post</span><span class="p">::</span> <span class="mi">2016</span><span class="o">-</span><span class="mi">03</span><span class="o">-</span><span class="mi">15</span> <span class="mi">09</span><span class="p">:</span><span class="mi">00</span>
<span class="p">:</span><span class="n">tags</span><span class="p">:</span> <span class="n">writing</span><span class="p">,</span> <span class="n">stc</span><span class="p">,</span> <span class="n">sphinx</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">post</span></code> adds the document to the set of posts.
You can show a post listing by using the <code class="docutils literal notranslate"><span class="pre">postlist</span></code> directive:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">postlist</span><span class="p">::</span>
<span class="p">:</span><span class="n">tags</span><span class="p">:</span> <span class="n">stc</span>
</pre></div>
</div>
<p>This shows some of the magical things you can do with Sphinx’s extensibility.
If you’re curious,
this article was actually written in reStructuredText and then exported to Word for publishing.
You can see the full source here: <a class="reference external" href="https://github.com/ericholscher/ericholscher.com/blob/master/site/blog/2016/jul/1/sphinx-and-rtd-for-writers.rst">https://github.com/ericholscher/ericholscher.com/blob/master/site/blog/2016/jul/1/sphinx-and-rtd-for-writers.rst</a></p>
</section>
<section id="custom-builders">
<h2>Custom builders</h2>
<p>Sphinx supports custom builders to perform tasks beyond providing basic output formats.
Some examples that ship with Sphinx:</p>
<ul class="simple">
<li><p>A linkcheck builder that tells you about broken URL’s</p></li>
<li><p>A builder that outputs all the changes in the latest version of your code for a changelog</p></li>
<li><p>An XML builder that outputs a representation of your documents in XML</p></li>
<li><p>A Man page builder that builds man pages from your documentation</p></li>
<li><p>JSON builder that outputs your pages as HTML inside of JSON, with some metadata, for embedding dynamically</p></li>
</ul>
<p>You can get as creative as you like with custom builders,
which is another place to extend Sphinx outside of the markup.</p>
</section>
<section id="tradeoffs-with-sphinx">
<h2>Tradeoffs with Sphinx</h2>
<p>Every tool has its issues and limitations.
I’d like to address some of the issues with Sphinx,
so that you can go into it with eyes wide open.</p>
<p>The biggest issue is that it is originally a <em>programmer tool</em>.
This means that a lot of the designs assume knowledge of code,
especially for installation and extending the tools.
Knowledge of the command line is definitely required.</p>
<p>The markup language,
reStructuredText,
is also a bit finicky.
It depends on whitespace for separation of content,
which is a natural concept for Python programmers,
but not for most writers.</p>
<p>In general though,
a lot of the complexity in the language comes from the extensibility and power.
When compared to something like Markdown,
reStructuredText can do so much more that it’s worth the complexity and somewhat steep learning curve.</p>
</section>
<section id="introduction-to-read-the-docs">
<h2>Introduction to Read the Docs</h2>
<p>Read the Docs is a hosting platform for Sphinx-generated documentation.
It takes the power of Sphinx and adds version control,
full-text search,
and other useful features.
It pulls down code and doc files from Git,
Mercurial,
or Subversion,
then builds and hosts your documentation.
We’ll use GitHub in this example as it’s the most commonly used system for accessing code.</p>
<p>To get started,
you create a Read the Docs account,
and link your GitHub account.
Then you select the GitHub repository you’d like to build documentation for,
at which point the magic happens.</p>
<p>Read the Docs will:</p>
<ul class="simple">
<li><p>Clone your repository</p></li>
<li><p>Build HTML, PDF, and ePub versions of your documentation from your <code class="docutils literal notranslate"><span class="pre">master</span></code> branch.</p></li>
<li><p>Index your documentation to allow full-text-search</p></li>
<li><p>Create Version objects from each <em>tag</em> and <em>branch</em> in your repository, allowing you to optionally host those as well</p></li>
<li><p>Activate a webhook on your repository, so when you push code to any branch, your documentation is rebuilt</p></li>
</ul>
<p>Now,
whenever you commit new code or documentation to your repository,
your documentation is kept up to date.
This works with your <code class="docutils literal notranslate"><span class="pre">master</span></code> branch,
as well as any other branches or tags you might have activated documentation for.</p>
<p>Read the Docs has two special versions:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">latest</span></code> which maps to the most up to date development version of your software</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stable</span></code> which maps to the latest tagged release of your software</p></li>
</ul>
<p>These are version aliases that help maintain stable URLs for the most up-to-date commits or for the most stable released version of your software.</p>
<p>We built Read the Docs to be “set it and forget it”.
Once you set your project up and activate the versions you want hosted,
we sit downstream of your version control system and just keep your documentation up to date.
It feels pretty magical once it’s set up,
and takes the thankless task of deploying documentation out of your day.</p>
<section id="recommended-versioning-system">
<h3>Recommended Versioning System</h3>
<p>Read the Docs only works with version control.
This means that however you version your software,
your documentation follows suit.
This is great for integrating with your development team,
but it also means you need to think about the proper strategy for versioning.</p>
<p>After working with a lot of open source projects,
we generally recommend this workflow for projects:</p>
<ul class="simple">
<li><p>A <code class="docutils literal notranslate"><span class="pre">master</span></code> branch that the next release of your software is developed on</p></li>
<li><p>Git <em>branches</em> for ongoing maintenance of each version of your software that is maintained</p></li>
<li><p>Git <em>tags</em> for specific released versions that users might be using</p></li>
</ul>
<p>We recommend release branches because it allows you to update them over time.
Git <em>tags</em> are static,
so they are appropriate for specific versions that a user might have installed.</p>
<p>An example:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">master</span></code> is your 2.2 release that isn’t out yet</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">2.1.X</span></code> is your release branch for the <code class="docutils literal notranslate"><span class="pre">2.1</span></code> version</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">2.1.1</span></code> is a similar tag of your <code class="docutils literal notranslate"><span class="pre">2.1</span></code> branch, with the latest release</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">2.1.0</span></code> is the first tag of your <code class="docutils literal notranslate"><span class="pre">2.1</span></code> branch</p></li>
</ul>
</section>
<section id="additional-read-the-docs-features">
<h3>Additional Read the Docs Features</h3>
<p>Read the Docs also provides the following features:</p>
<ul class="simple">
<li><p>GitHub, Bitbucket, and Gitlab webhooks</p></li>
<li><p>Custom domain hosting</p></li>
<li><p>Full-text search for all your projects’ versions</p></li>
<li><p>Status badges to show your docs are up to date</p></li>
<li><p>Hosting of multiple languages for a specific project</p></li>
<li><p>Hosting of multiple projects on a single domain with “subprojects”</p></li>
</ul>
<p>Feel free to email me or find me at a conference if you want to talk more about these concepts,
or have ideas for other neat features.</p>
</section>
</section>
<section id="real-life-examples">
<h2>Real Life Examples</h2>
<p>Read the Docs has a large number of users across many different programming languages.
This is in part because Sphinx is such a powerful and dynamic tool,
and Read the Docs makes it easy and free to host docs for your open source project.</p>
<p>Here are some examples that show the wide range of projects using Sphinx & Read the Docs:</p>
<ul class="simple">
<li><p>ASP.NET - Microsoft’s web framework: <a class="reference external" href="https://docs.asp.net">https://docs.asp.net</a></p></li>
<li><p>Julia - A language for scientific computing: <a class="reference external" href="http://docs.julialang.org">http://docs.julialang.org</a></p></li>
<li><p>Jupyter - An interactive programming environment: <a class="reference external" href="http://jupyter.readthedocs.io">http://jupyter.readthedocs.io</a></p></li>
<li><p>PHPMyAdmin - A web-based database editor: <a class="reference external" href="https://docs.phpmyadmin.net">https://docs.phpmyadmin.net</a></p></li>
<li><p>Write the Docs - The community site for Write the Docs - <a class="reference external" href="http://www.writethedocs.org">http://www.writethedocs.org</a></p></li>
</ul>
<p>As you can see,
a wide range of projects are using the tools for many different uses.
It’s a powerful tool for writing prose as well as documenting source code.</p>
</section>
<section id="going-forward">
<h2>Going Forward</h2>
<p>Sphinx is an incredibly powerful tool.
Read the Docs builds on top 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.</p>
<p>I firmly believe that 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 your software documentation project.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Eric Holscher offers <a class="reference external" href="https://readthedocs.com/services/">consulting and contracting</a> on work related to Sphinx. If you want help implementing it in your organization, feel free to reach out and hopefully we can work together.</p>
</div>
</section>
</section>
Treating documentation as code is becoming a major theme in the software industry.
This is coming from both sides,
with developers starting to treat documentation as a priority alongside tests and code,
and writers seeing a lot of value in integrating more into the development process.
This marrying of cultures isn’t simple,
but having the proper tools for the job makes both sides happy with the process and the results that get produced.2016-07-01T00:00:00+00:00