DjangoMaine October Meet-up Slides for John Costa's talk on ReadTheDocs

1. How to (Really)
ReadTheDocs
https:/
/readthedocs.org/
John Costa
@johncosta
Wednesday, October 23, 13

2. About Me
Developer Support Engineer at DotCloud
Introduced to Python through Django when
0.96 was released.
Wednesday, October 23, 13

3. Overview
Documentation In General
ReadTheDocs - What is it?
ReadTheDocs - Setting up an open source
project
Wednesday, October 23, 13

4. Documentation
How many people document their code?
Why bother?
Wednesday, October 23, 13

5. Documentation
Why?
Not all code is obvious. Complex code is
complex.
Business rules may be readable, but don’t
explain why they are there.
Finding details takes a long time...it wastes
money to keep re-finding these details
Wednesday, October 23, 13

6. Documentation
Why?
Dependencies between systems may not be
obvious
Helps keep your project in scope (maybe) :)
Not everyone is thinking in the same context
at the same time.
Wednesday, October 23, 13

7. Documentation
What?
Dependencies
Installation instructions
Guides - like a readme
Things like change logs
Information about supported languages,
runtime, and tool versions
Wednesday, October 23, 13

8. Documentation
Where?
In a wiki?
What happens when code changes?
What if you need to support multiple
versions?
Self hosted, self managed process (script
that rebuilds documentation)
Wednesday, October 23, 13

9. Documentation
“Readability is a primary focus for Python
developers, in both project and code
documentation.”
- Kenneth Reitz, The Hitchhiker's Guide to
Python (python-guide)
“Documentation is communication”
- Jacob Kaplan-Moss, pycon-2011-writinggreat-documentation
Wednesday, October 23, 13

10. ReadTheDocs
Free(!!) hosting for Open Source documentation
Created by Eric Holscher, Charles Leifer, and
Bobby Grace for the 2010 Django Dash
Goals:
It was created to make hosting documentation
simple!
To create a central platform for people to find
documentation (search)
Wednesday, October 23, 13

11. ReadTheDocs
Architecture
Wednesday, October 23, 13

12. Read The Docs
Documentation Start
RTD Setup
RTD Post-Commit Hook
Wednesday, October 23, 13

13. ReadTheDocs
Documentation Start
$ pip install sphinx
$ mkdir docs && cd docs
$ sphinx-quickstart
$ make html
Wednesday, October 23, 13

14. ReadTheDocs
RTD Setup
Wednesday, October 23, 13

15. ReadTheDocs
RTD Setup
Wednesday, October 23, 13

16. ReadTheDocs
RTD Setup
Wednesday, October 23, 13

17. ReadTheDocs
RTD Post-Commit Hook
Wednesday, October 23, 13

18. ReadTheDocs
RTD Post-Commit Hook
Wednesday, October 23, 13

19. ReadTheDocs
RTD Post-Commit Hook
Wednesday, October 23, 13

20. ReadTheDocs
Private RTD
Can you do it...yes!
Set it up like any other django application
stack
Or (beta)
Wednesday, October 23, 13

21. Things We Didn’t talk
about
Sphinx
ReStructuredText(reST)
Documentation Conventions
Wednesday, October 23, 13

22. Resources/References
ReStructuredText(reST):
http:/
/restructuredtext-philosophy.readthedocs.org/en/latest/
index.html
http:/
/thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
Python Documentation Conventions
http:/
/www.python.org/dev/peps/pep-0008/#comments
Wednesday, October 23, 13

23. Resources/References
On Documentation:
http:/
/blip.tv/pycon-usvideos-2009-2010-2011/pycon-2011writing-great-documentation-4899042
Wednesday, October 23, 13

24. Resources/References
https:/
/docs.readthedocs.org/en/latest/
index.html
http:/
/programmers.stackexchange.com/
questions/121775/why-should-you-documentcode/121787
http:/
/programmers.stackexchange.com/
questions/152325/where-to-put-codedocumentation
Wednesday, October 23, 13

25. Resources/References
http:/
/blog.clojurewerkz.org/blog/
2013/04/20/how-to-make-your-open-sourceproject-really-awesome/
http:/
/coding.smashingmagazine.com/
2013/01/03/starting-open-source-project/
http:/
/ericholscher.com/blog/2012/jan/22/
why-read-docs-matters/
Wednesday, October 23, 13

26. Thank You!
@johncosta
Wednesday, October 23, 13