Introduction to Sphinx

& Read the Docs

Eric Holscher
Pycon PH
February 22 2014
 Who am I

• Maintainer of Read the Docs

• Co-Organizer of Write the Docs
• Traveling Asia and figured I would
come say hi :)
 What you should do

• Stop me if anything is unclear

• Stop me if I’m talking too fast
• Ask questions
• Learn something :)
What we will talk about
today
• Why Write Docs
• reStructuredText
• Sphinx
• Read the Docs
Because everyone has a
mascot..
Documentation Sloth
Why Write Docs
You will be using your
code in 6 months
You want people to use
your code
You want people to help
out
It makes your code
better
You want to be a better
writer
!
!
Overview
!
!
+----------------------------------------------------------+
| |
| Read the Docs |
| +----------------------------------------------+ |
| | | |
| | Sphinx | |
| | +-----------------------------------+ | |
| | | | | |
| | | Docutils | | |
| | | +--------------------+ | | |
| | | | | | | |
| | | | reStructuredText | | | |
| | | | | | | |
| | | +--------------------+ | | |
| | | | | |
| | | | | |
| | | | | |
| | +-----------------------------------+ | |
| | | |
| | | |
| | | |
| +----------------------------------------------+ |
| |
| |
+----------------------------------------------------------+
reStructuredText
 Lightweight
Markup Language
 Lightweight Markup
Language
• reStructuredText is the one Sphinx uses
• Used to write plain text files that
contain markup that can rendered
more richly in other formats

• Base format to generate other formats

from

• Readable as plain text

• Works well with programmer tools
 Semantic Meaning

• The power of HTML, and LWML

• Semantics mean you are saying what
something is, not how to display it

• Once you know what it is, you can

display it properly
 Classic HTML Example
# HTML (Bad)
<b>issue 72</b>
!
# HTML (Good)
<span class=“issue”>issue 72</span>
# CSS
.issue { text-format: bold; }
 Classic LWML Example
# Bad
<font color=“red”>Warning: Don’t do this!</font>
!
# Good
<span class=“warning”>Don’t do this!</span>
!
# Best
.. warning:: Don’t do this
 Semantic Markup

• Shows the intent of your words

• Works across output formats
• You can style warnings differently in
html, PDF, epub, etc.
 Markdown vs. reST
• A worthwhile and contentious debate
• Markdown is JUST for HTML
• reStructuredText does more, thus is
more complex

• reStructuredText is ugly, not only

because of the complexity

• I wish I could use Markdown, but need

reStructuredText
 If you care about your
words, you should write
in a way that preserves
 Example

• http://localhost:5000/?
n=7d0e494702eae1b108b2245404b84e5b
&theme=nature
 Understanding
reStructuredText
 Sections

• Used to give documents hierarchy

• Similar to h1, h2, h3 in HTML
• Doesn’t matter what characters you use,
just be consistent
 Sections Example
Project
=======
!
Tutorial
--------
!
Welcome to our tutorial
!
Step 1
^^^^^^
!
* Go to your dashboard
* Click the thing
Sections Example
 Hyperlinks
• Hyperlinks are made by appending an
underscore_

• Use back ticks for grouping of many

words

• `This is a link`_
• Generally best to always use back ticks
 Hyperlinks

• Hyperlink targets are defined later in

the file

• .. _This is a link: http://example.com

 Hyperlinks Example

Check out our `website`_

!
.. _website: http://pycon.python.ph
 Page Level Markup

• A line that starts with “.. “, 2 periods

and whitespace

• Ends at the next un-indented line

• Used for page-level markup
 Directives
• “.. directive-name::”
• Two colons are used because they will
likely never be used in text content

• Main source of extendability

• A lot of Sphinx’s power comes through
Directives
 Directive Example
.. code-block:: python
:linenos:
!

print “wooo”
 Inline Markup
• one asterisk: *text* for emphasis
(italics)

• two asterisks: **text** for strong

emphasis (bold)

• backquotes: ``text`` for code samples

• hyperlinks: `link`_
Interpreted Text Roles

• Example of Inline Markup

• Look like :role:`target`
• Sphinx uses these for a lot
• :pep:`8` will create a link to PEP 8
 Interpreted Text Role
Example
.. _my-reference-label:
!
Section to cross-reference
--------------------------
!
This is the text of the section.
!
It refers to itself, see :ref:`my-reference-label`.
Interpreted Text Role
Example
 Kinda crazy, I know.
But really powerful!
 reStructuredText
• The best LWML that I know of
• Gives you the most semantic meaning
• Most extensible
• Sphinx adds documentation semantics
to reStructuredText

• Play with it at http://rst.ninjs.org

Questions?
Sphinx
Understanding Sphinx
 Sphinx

• Documentation Generator
• Takes reST files and turns it into
HTML/PDF/etc

• Adds lots of little nice things specific to

writing tech documentation
 Basic Sphinx Layout

project/
docs/
conf.py
index.rst
Makefile
 Build your Docs

• Put RST into a directory

• Run `make html`
Sphinx Additions
 TOC Tree

• Table of Contents Tree

• Allows hierarchal notion of documents
• Gives you a nice index page of all your
content

• .. toctree:: Table of Contents

 Syntax Highlighting

• Uses Pygments Library

• Highlights basically everything
• .. source-code:: ruby
 Autodoc
• Pulls docstrings from your classes and
methods

• Runs dynamically so it’s always up to

date with your source code

• A bit hard to work with, because it’s

made to be manually edited

• .. class:: django.core.views.View
 Cross-referencing
• Allows you to reference content in other
documents

• Intersphinx extension lets you

reference content in other projects

• :ref:`python:keywords`
• :doc:`tutorial`
 Tons of code-specific
Markup

• Environmental Variables, RFC’s,

Tokens, Keywords, Classes, Filenames,
Man pages, etc.

• :rfc:`1984`
 Extensions

• Ships with lots of useful extensions

• Has an API for defining your own
• Ships with doctest runner, coverage
stats, graphviz support, todo lists,
viewing source code, etc.
 Sphinx

• Best documentation tool I know of

• Great community and lots of prior art
• So good, that I built an entire website
around it :)
Questions?
Read the Docs
 Read the Docs
• Builds and hosts Sphinx documentation
• Defacto hosting provider for Python
documentation

• Created in 48 hours in 2010 Django

Dash

• Provides a lot of value on top of Sphinx

Read the Docs
 RTD Stats
• 40 people contributed code
• 3,548 commits
• 700 issues
• 1,180,000 builds
• 130 million pageviews, 9M a month
• http://ericholscher.com/blog/2013/dec/
Read the Docs Features
 Beautiful Theme

• Designed by Dave Snider (a real

designer!)

• Looks great on mobile

• Beautiful fonts and colors
Beautiful Theme
 Versions

• Based on your VCS

• Every tag and branch convert into a
version

• Build and host old versions of your

docs, for users who still use them
 Post Commit Hooks

• We support GitHub and BitBucket

• Your docs build automatically when you
push a new commit

• Your docs are always up to date

 Translations

• Host multiple languages of your docs

• Host one version of your docs, not in
English :)
 Localization

• The main readthedocs.org site is

localized

• We now have 6 languages that are

suported
 Search

• We index everything into Elastic Search

• Provide full-text search of your
documentation

• Much better than the built-in Sphinx

search, since we can use a server
 CNAMEs

• Host your docs on your own domain

• http://docs.fabfile.org
 Multiple Formats

• PDF
• Zipped HTML
• ePub
• Man Pages
• Dash Docsets
 Good SEO

• readthedocs.org is heavily indexed by

Google

• We use Canonical URL tags to make

sure your latest docs get indexed
 Highly Available

• We host everything with redundant app

servers straight from nginx, without
touching a database

• Never had significant (multi-hour)

downtime of documentation serving
 Lots of small things

• Serve multiple projects on one CNAME

• Have multiple people manage a project
• Python 3
• Virtualenv & requirements.txt support
Using Read the Docs
 Using RTD

• Register for an account

• Import your project with Sphinx
documentation

• There is no step 3
`
 Recap

• Why Write Documentation

• Why reST and Sphinx exist and how
they work

• Why Read the Docs is awesome :)

 Sprints

• I’ll be here sprinting on Read the Docs

• Come find me to help or ask questions
 Malcolm

• Helped me at my first Django Sprint

 Questions?

• @ericholscher
• [email protected]
• Come talk to me :)