Lightweight Markup
Language
• Base format to generate other formats
from
• Readable as plain text
• Works well with programmer tools
Slide 15
Slide 15 text
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
Slide 16
Slide 16 text
# HTML (Bad)
issue 72
!
# HTML (Good)
issue 72
# CSS
.issue { text-format: bold; }
Classic HTML Example
Slide 17
Slide 17 text
# Bad
Warning: Don’t do this!
!
# Good
Don’t do this!
!
# Best
.. warning:: Don’t do this
Classic LWML Example
Slide 18
Slide 18 text
Semantic Markup
• Shows the intent of your words
• Works across output formats
• You can style warnings differently in
HTML, PDF, epub, man pages, etc.
Slide 19
Slide 19 text
Markdown vs. reST
• Markdown is JUST for HTML
• reStructuredText does more, thus is
more complex
• reStructuredText is ugly, not only
because of the complexity
Slide 20
Slide 20 text
If you care about your
words, you should write
in a way that preserves
semantic meaning!
Slide 21
Slide 21 text
Example
• http://localhost:5000/?
n=0504a23099c0b07e34e0a30fc6432009
&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
Interpreted Text Roles
• Good example of 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`.
Interpreted Text Role
Example
Slide 30
Slide 30 text
Interpreted Text Role
Example
Slide 31
Slide 31 text
Extension Point Review
• Directives for page level markup
• Interpreted Text Roles for inside
paragraphs
Slide 32
Slide 32 text
reStructuredText
Review
• 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
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:: Table of 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`
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
• .. class:: django.core.views.View
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
Questions?
Slide 48
Slide 48 text
Read the Docs
Slide 49
Slide 49 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
Open Source
• https://github.com/rtfd/
readthedocs.org
Slide 57
Slide 57 text
Fast Forward to Today
Slide 58
Slide 58 text
RTD Stats
• 118 people have contributed code
• 3,801 commits
• 844 issues
• 1,475,000 builds
• 150 million pageviews, 9M a month
• http://ericholscher.com/blog/2013/dec/
23/read-the-docs-2013-stats/
Slide 59
Slide 59 text
No content
Slide 60
Slide 60 text
Read the Docs Features
Slide 61
Slide 61 text
Beautiful Theme
• Designed by Dave Snider (a real
designer!)
• Looks great on mobile
• Beautiful fonts and colors
Slide 62
Slide 62 text
Beautiful Theme
Slide 63
Slide 63 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 64
Slide 64 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 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
• Man Pages
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
• Serve multiple projects on one CNAME
• 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
Demo
Slide 75
Slide 75 text
Recap
• Why Write Documentation
• Why reST and Sphinx exist and how
they work
• Why Read the Docs is awesome :)