Introduction to Sphinx & Read the Docs

Transcript

1. Eric Holscher eric@ericholscher.com Introduction to Sphinx & Read the Docs
2. What we will talk about today • Why Write Docs • reStructuredText • Sphinx • Read the Docs
3. Who am I • Maintainer of Read the Docs • Co-Organizer of Write the Docs
4. What you should do • Stop me if anything is unclear • Stop me if I’m talking too fast • Ask questions • Learn something :)
5. Why Write Docs
6. You will be using your code in 6 months
7. You want people to use your code
8. It makes your code better
9. You want to be a better writer
10. Questions?
11. ! ! ! ! +----------------------------------------------------------+ | | | Read the Docs | | +----------------------------------------------+ | | | | | | | Sphinx | | | | +-----------------------------------+ | | | | | | | | | | | Docutils | | | | | | +--------------------+ | | | | | | | | | | | | | | | reStructuredText | | | | | | | | | | | | | | | +--------------------+ | | | | | | | | | | | | | | | | | | | | | | | +-----------------------------------+ | | | | | | | | | | | | | | | +----------------------------------------------+ | | | | | +----------------------------------------------------------+ Tech Overview
12. reStructuredText
13. Lightweight Markup Language
14. Lightweight Markup Language • Base format to generate other formats from • Readable as plain text • Works well with programmer tools
15. 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
16. # HTML (Bad) <b>issue 72</b> ! # HTML (Good) <span class=“issue”>issue 72</span> # CSS .issue { text-format: bold; } Classic HTML Example
17. # 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 LWML Example
18. Semantic Markup • Shows the intent of your words • Works across output formats • You can style warnings differently in HTML, PDF, epub, man pages, etc.
19. Markdown vs. reST • Markdown is JUST for HTML • reStructuredText does more, thus is more complex • reStructuredText is ugly, not only because of the complexity
20. If you care about your words, you should write in a way that preserves semantic meaning!
21. Example • http://localhost:5000/? n=0504a23099c0b07e34e0a30fc6432009 &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. Interpreted Text Roles • Good example of 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`. Interpreted Text Role Example
30. Interpreted Text Role Example
31. Extension Point Review • Directives for page level markup • Interpreted Text Roles for inside paragraphs
32. 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
33. Questions?
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:: Table of 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`
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 • .. class:: django.core.views.View
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. Questions?
48. Read the Docs
49. 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
50. Story of Read the Docs
51. 2010 Django Dash
52. Charles Leifer Bobby Grace (Design) Me
53. Doc Hosting Sucks • packages.python.org • GitHub Pages • Cron Jobs
55. Had a workable site in 48 Hours
56. Open Source • https://github.com/rtfd/ readthedocs.org
57. Fast Forward to Today
58. 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/
60. Read the Docs Features
61. Beautiful Theme • Designed by Dave Snider (a real designer!) • Looks great on mobile • Beautiful fonts and colors
62. Beautiful Theme
63. 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
64. 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
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 • Man Pages
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 • Serve multiple projects on one CNAME • 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. Demo
75. Recap • Why Write Documentation • Why reST and Sphinx exist and how they work • Why Read the Docs is awesome :)
76. Resources • http://docs.writethedocs.org/ • http://docs.readthedocs.org/ • http://sphinx-doc.org/
77. Questions? • @ericholscher • eric@ericholscher.com • Come talk to me around the conference