Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Introduction to Sphinx & Read the Docs Djangoco...

ericholscher
September 08, 2015

Introduction to Sphinx & Read the Docs Djangocon 2015

A presentation I gave at Djangocon 2015.

ericholscher

September 08, 2015
Tweet

More Decks by ericholscher

Other Decks in Technology

Transcript

  1. Who am I • Co-Founder of Read the Docs •

    Co-Founder of Write the Docs
  2. What we will talk about today • Why Write Docs

    • reStructuredText • Sphinx • Read the Docs
  3. +----------------------------------------------------------+ | | | Read the Docs | | +----------------------------------------------+

    | | | | | | | Sphinx | | | | +-----------------------------------+ | | | | | | | | | | | Docutils | | | | | | +--------------------+ | | | | | | | | | | | | | | | reStructuredText | | | | | | | | | | | | | | | +--------------------+ | | | | | | | | | | | | | | | | | | | | | | | +-----------------------------------+ | | | | | | | | | | | | | | | +----------------------------------------------+ | | | | | +----------------------------------------------------------+ Tech Overview
  4. Lightweight Markup Language • Base format to generate other formats

    from • Readable as plain text • Works well with programmer tools
  5. 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”
  6. # HTML (Bad) <b>issue 72</b> # HTML (Good) <span class=“issue”>issue

    72</span> # CSS .issue { text-format: bold; } Classic HTML Example
  7. # 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 Classic RST Example
  8. Semantic Markup • Shows the intent of your words •

    Works across output formats • You can style warnings differently in HTML, PDF, ePub, etc.
  9. 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
  10. If you care about your words, you should write in

    a way that preserves semantic meaning!
  11. Page Level Markup • A line that starts with “..

    “, 2 periods and whitespace • Ends at the next un-indented line
  12. Directives • .. directive-name:: • Main source of extendability •

    A lot of Sphinx’s power comes through Directives
  13. .. code-block:: python :linenos: from datetime import datetime time =

    datetime.now() print time Directive Example
  14. Inline Markup • Anything that is included in the page

    content itself • Used for embedding things into the rendered output
  15. .. _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
  16. Extension Point Review • Directives for page level markup •

    Interpreted Text Roles for inside paragraphs
  17. Sphinx • Best documentation tool I know of • Great

    community and lots of prior art • So good, that I built an entire website around it :)
  18. TOC Tree • Table of Contents Tree • Allows hierarchal

    notion of documents • Gives you a nice index page of all your content • .. toctree:: Sweet Contents
  19. Cross-referencing • Allows you to reference content in other documents

    • Intersphinx extension lets you reference content in other projects • :ref:`python:keywords` • :doc:`tutorial`
  20. Tons of code-specific Markup • Environmental Variables, RFC’s, Tokens, Keywords,

    Classes, Filenames, Man pages, etc. • :rfc:`1984` • :pep:`8`
  21. 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.
  22. 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
  23. Sphinx Review • Documentation Generator • Takes reST files and

    turns it into HTML/PDF/etc • Adds lots of nice markup specific to writing tech documentation
  24. 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
  25. RTD Stats • 5,822 commits • 1622 issues • 3.3M

    builds • 320 million pageviews, 15M a month • https://blog.readthedocs.com/read-the- docs-2014-stats/
  26. Beautiful Theme • Designed by Dave Snider (a real designer!)

    • Looks great on mobile • Beautiful fonts and colors
  27. 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
  28. 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
  29. Translations • Host multiple languages of your docs • Host

    one version of your docs, not in English :)
  30. 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
  31. 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
  32. Lots of small things • Build failure emails • Have

    multiple people manage a project • Python 3 • Virtualenv & requirements.txt support
  33. Using RTD • Register for an account • Import your

    project with Sphinx documentation • There is no step 3
  34. Recap • Why Write Documentation • Why reST and Sphinx

    exist and how they work • Why Read the Docs is awesome :)
  35. 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
  36. “I can’t say I’m self taught. I’ve been taught by

    the people who wrote the documentation” - @soulshake