Introduction to Sphinx & Read the Docs Djangocon 2015

A presentation I gave at Djangocon 2015.

Transcript

1. Eric Holscher eric@ericholscher.com Introduction to Sphinx & Read the Docs
2. Who am I • Co-Founder of Read the Docs • Co-Founder of Write the Docs
3. What we will talk about today • Why Write Docs • reStructuredText • Sphinx • Read the Docs
4. Why Write Docs
5. You will be using your code in 6 months
6. You want people to use your code
7. It makes your code better
8. You want to be a better writer
9. +----------------------------------------------------------+ | | | Read the Docs | | +----------------------------------------------+ | | | | | | | Sphinx | | | | +-----------------------------------+ | | | | | | | | | | | Docutils | | | | | | +--------------------+ | | | | | | | | | | | | | | | reStructuredText | | | | | | | | | | | | | | | +--------------------+ | | | | | | | | | | | | | | | | | | | | | | | +-----------------------------------+ | | | | | | | | | | | | | | | +----------------------------------------------+ | | | | | +----------------------------------------------------------+ Tech Overview
10. reStructuredText
11. Lightweight Markup Language
12. Lightweight Markup Language • Base format to generate other formats from • Readable as plain text • Works well with programmer tools
13. 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”
14. # HTML (Bad) <b>issue 72</b> # HTML (Good) <span class=“issue”>issue 72</span> # CSS .issue { text-format: bold; } Classic HTML Example
15. # 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
16. # Markdown Check out [PEP 8](https:// www.python.org/dev/peps/pep-0008/) # RST Check out :pep:`8` Markdown vs. RST
17. Semantic Markup • Shows the intent of your words • Works across output formats • You can style warnings differently in HTML, PDF, ePub, etc.
18. 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
19. If you care about your words, you should write in a way that preserves semantic meaning!
20. RST • Whitespace Sensitive (Like Python) • Extensible • Powerful, but slightly awkward
21. Example • http://localhost:5000/? n=84c9a8d71ad9d4e6dd94504a 3c65f6 &theme=nature
22. Understanding reStructuredText Extensibility
23. Page Level Markup • A line that starts with “.. “, 2 periods and whitespace • Ends at the next un-indented line
24. Directives • .. directive-name:: • Main source of extendability • A lot of Sphinx’s power comes through Directives
25. .. code-block:: python :linenos: from datetime import datetime time = datetime.now() print time Directive Example
26. Directive Example
27. Inline Markup • Anything that is included in the page content itself • Used for embedding things into the rendered output
28. Inline Markup • Look like :role:`target` • :pep:`8` will create a link to PEP 8
29. .. _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
30. Inline Markup Example
31. Code Docs Module Level Page Level Markup Class Level Inline Markup
32. Extension Point Review • Directives for page level markup • Interpreted Text Roles for inside paragraphs
33. RST Review • Gives you semantic meaning • Amazingly extensible • Play with it at http://rst.ninjs.org
34. Sphinx
35. Understanding Sphinx
36. project/ docs/ conf.py Makefile index.rst tutorial.rst … Basic Sphinx Layout
37. Build your Docs • Put RST into your docs directory • Run `make html`
38. Sphinx • Best documentation tool I know of • Great community and lots of prior art • So good, that I built an entire website around it :)
39. Sphinx Additions
40. TOC Tree • Table of Contents Tree • Allows hierarchal notion of documents • Gives you a nice index page of all your content • .. toctree:: Sweet Contents
41. Cross-referencing • Allows you to reference content in other documents • Intersphinx extension lets you reference content in other projects • :ref:`python:keywords` • :doc:`tutorial`
42. Tons of code-specific Markup • Environmental Variables, RFC’s, Tokens, Keywords, Classes, Filenames, Man pages, etc. • :rfc:`1984` • :pep:`8`
43. Syntax Highlighting • Uses Pygments Library • Highlights basically everything • .. source-code:: ruby
44. 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.
45. 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
46. Sphinx Review • Documentation Generator • Takes reST files and turns it into HTML/PDF/etc • Adds lots of nice markup specific to writing tech documentation
47. Read the Docs
48. 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
49. Story of Read the Docs
50. 2010 Django Dash
51. Charles Leifer Bobby Grace (Design) Me
52. Doc Hosting Sucks • packages.python.org • GitHub Pages • Cron Jobs
54. Had a workable site in 48 Hours
55. Open Source • https://github.com/rtfd/ readthedocs.org
56. Fast Forward to Today
57. 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/
59. Read the Docs Features
60. Beautiful Theme • Designed by Dave Snider (a real designer!) • Looks great on mobile • Beautiful fonts and colors
61. Beautiful Theme
62. 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
63. 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
64. Markdown Support • Newly added • Can write in CommonMark or RST in a project
65. Translations • Host multiple languages of your docs • Host one version of your docs, not in English :)
66. Localization • The main readthedocs.org site is localized • We now have 8 languages that are suported
67. 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
68. CNAMEs • Host your docs on your own domain • http://docs.fabfile.org
69. Multiple Formats • HTML • PDF • Zipped HTML • ePub
70. 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
71. Lots of small things • Build failure emails • Have multiple people manage a project • Python 3 • Virtualenv & requirements.txt support
72. Using Read the Docs
73. Using RTD • Register for an account • Import your project with Sphinx documentation • There is no step 3
74. Recap • Why Write Documentation • Why reST and Sphinx exist and how they work • Why Read the Docs is awesome :)
75. 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
76. “I can’t say I’m self taught. I’ve been taught by the people who wrote the documentation” - @soulshake
77. Thanks • @ericholscher • eric@ericholscher.com • Come talk to me around the conference