How to ReadTheDocs

1,646 views

Published on

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

Published in: Technology, Education
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,646
On SlideShare
0
From Embeds
0
Number of Embeds
8
Actions
Shares
0
Downloads
14
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

How to ReadTheDocs

  1. 1. How to (Really) ReadTheDocs https:/ /readthedocs.org/ John Costa @johncosta Wednesday, October 23, 13
  2. 2. About Me Developer Support Engineer at DotCloud Introduced to Python through Django when 0.96 was released. Wednesday, October 23, 13
  3. 3. Overview Documentation In General ReadTheDocs - What is it? ReadTheDocs - Setting up an open source project Wednesday, October 23, 13
  4. 4. Documentation How many people document their code? Why bother? Wednesday, October 23, 13
  5. 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. 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. 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. 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. 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. 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. 11. ReadTheDocs Architecture Wednesday, October 23, 13
  12. 12. Read The Docs Documentation Start RTD Setup RTD Post-Commit Hook Wednesday, October 23, 13
  13. 13. ReadTheDocs Documentation Start $ pip install sphinx $ mkdir docs && cd docs $ sphinx-quickstart $ make html Wednesday, October 23, 13
  14. 14. ReadTheDocs RTD Setup Wednesday, October 23, 13
  15. 15. ReadTheDocs RTD Setup Wednesday, October 23, 13
  16. 16. ReadTheDocs RTD Setup Wednesday, October 23, 13
  17. 17. ReadTheDocs RTD Post-Commit Hook Wednesday, October 23, 13
  18. 18. ReadTheDocs RTD Post-Commit Hook Wednesday, October 23, 13
  19. 19. ReadTheDocs RTD Post-Commit Hook Wednesday, October 23, 13
  20. 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. 21. Things We Didn’t talk about Sphinx ReStructuredText(reST) Documentation Conventions Wednesday, October 23, 13
  22. 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. 23. Resources/References On Documentation: http:/ /blip.tv/pycon-usvideos-2009-2010-2011/pycon-2011writing-great-documentation-4899042 Wednesday, October 23, 13
  24. 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. 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. 26. Thank You! @johncosta Wednesday, October 23, 13

×