Lightweight Markup
Language
• Base format to generate other formats
from
• Readable as plain text
• Works well with programmer tools
Slide 13
Slide 13 text
Semantic Meaning
• The power of HTML, and
reStructredText
• Semantics mean you are saying what
something is, not how to display it
• Once you know what it is, you can
display it properly
• “Separation of Concerns”
Slide 14
Slide 14 text
# HTML (Bad)
issue 72
# HTML (Good)
issue 72
# CSS
.issue { text-format: bold; }
Classic HTML Example
Slide 15
Slide 15 text
# Bad
Warning: Don’t do this!
# Good
Don’t do this!
# Best
.. warning:: Don’t do this
Classic RST Example
Slide 16
Slide 16 text
# Markdown
Check out [PEP 8](https://
www.python.org/dev/peps/pep-0008/)
# RST
Check out :pep:`8`
Markdown vs. RST
Slide 17
Slide 17 text
Semantic Markup
• Shows the intent of your words
• Works across output formats
• You can style warnings differently in
HTML, PDF, ePub, etc.
Slide 18
Slide 18 text
Markdown vs. reST
• Markdown is JUST for HTML, not
semantic
• reStructuredText does more, thus is
more complex
• reStructuredText is ugly, not only
because of the complexity
Slide 19
Slide 19 text
If you care about your
words, you should write
in a way that preserves
semantic meaning!
Example
• http://localhost:5000/?
n=84c9a8d71ad9d4e6dd94504a 3c65f6
&theme=nature
Slide 22
Slide 22 text
Understanding
reStructuredText
Extensibility
Slide 23
Slide 23 text
Page Level Markup
• A line that starts with “.. “, 2 periods
and whitespace
• Ends at the next un-indented line
Slide 24
Slide 24 text
Directives
• .. directive-name::
• Main source of extendability
• A lot of Sphinx’s power comes through
Directives
Slide 25
Slide 25 text
.. code-block:: python
:linenos:
from datetime import datetime
time = datetime.now()
print time
Directive Example
Slide 26
Slide 26 text
Directive Example
Slide 27
Slide 27 text
Inline Markup
• Anything that is included in the page
content itself
• Used for embedding things into the
rendered output
Slide 28
Slide 28 text
Inline Markup
• Look like :role:`target`
• :pep:`8` will create a link to PEP 8
Slide 29
Slide 29 text
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to itself, see :ref:`my-reference-label`.
Inline Markup Example
Build your Docs
• Put RST into your docs directory
• Run `make html`
Slide 38
Slide 38 text
Sphinx
• Best documentation tool I know of
• Great community and lots of prior art
• So good, that I built an entire website
around it :)
Slide 39
Slide 39 text
Sphinx Additions
Slide 40
Slide 40 text
TOC Tree
• Table of Contents Tree
• Allows hierarchal notion of documents
• Gives you a nice index page of all your
content
• .. toctree:: Sweet Contents
Slide 41
Slide 41 text
Cross-referencing
• Allows you to reference content in other
documents
• Intersphinx extension lets you
reference content in other projects
• :ref:`python:keywords`
• :doc:`tutorial`
Slide 42
Slide 42 text
Tons of code-specific
Markup
• Environmental Variables, RFC’s,
Tokens, Keywords, Classes, Filenames,
Man pages, etc.
• :rfc:`1984`
• :pep:`8`
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.
Slide 45
Slide 45 text
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
• .. autoclass:: ap.models.Poll
Slide 46
Slide 46 text
Sphinx Review
• Documentation Generator
• Takes reST files and turns it into
HTML/PDF/etc
• Adds lots of nice markup specific to
writing tech documentation
Slide 47
Slide 47 text
Read the Docs
Slide 48
Slide 48 text
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
Beautiful Theme
• Designed by Dave Snider (a real
designer!)
• Looks great on mobile
• Beautiful fonts and colors
Slide 61
Slide 61 text
Beautiful Theme
Slide 62
Slide 62 text
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
Slide 63
Slide 63 text
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
Slide 64
Slide 64 text
Markdown Support
• Newly added
• Can write in CommonMark or RST in a
project
Slide 65
Slide 65 text
Translations
• Host multiple languages of your docs
• Host one version of your docs, not in
English :)
Slide 66
Slide 66 text
Localization
• The main readthedocs.org site is
localized
• We now have 8 languages that are
suported
Slide 67
Slide 67 text
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
Slide 68
Slide 68 text
CNAMEs
• Host your docs on your own domain
• http://docs.fabfile.org
Slide 69
Slide 69 text
Multiple Formats
• HTML
• PDF
• Zipped HTML
• ePub
Slide 70
Slide 70 text
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
Slide 71
Slide 71 text
Lots of small things
• Build failure emails
• Have multiple people manage a project
• Python 3
• Virtualenv & requirements.txt support
Slide 72
Slide 72 text
Using Read the Docs
Slide 73
Slide 73 text
Using RTD
• Register for an account
• Import your project with Sphinx
documentation
• There is no step 3
Slide 74
Slide 74 text
Recap
• Why Write Documentation
• Why reST and Sphinx exist and how
they work
• Why Read the Docs is awesome :)
Slide 75
Slide 75 text
Support
• Come help develop RTD if you are
interested in this
• Help us triage Github Issues
• Get your company to Sponsor the
project
• Use readthedocs.com for your private
docs
Slide 76
Slide 76 text
“I can’t say I’m self taught.
I’ve been taught by the
people who wrote the
documentation”
- @soulshake
Slide 77
Slide 77 text
Thanks
• @ericholscher
• eric@ericholscher.com
• Come talk to me around the conference