how to readthedocs
DESCRIPTION
DjangoMaine October Meet-up Slides for John Costa's talk on ReadTheDocsTRANSCRIPT
How to (Really)ReadTheDocs
https://readthedocs.org/ John Costa@johncosta
Wednesday, October 23, 13
About Me
Developer Support Engineer at DotCloud
Introduced to Python through Django when 0.96 was released.
Wednesday, October 23, 13
Overview
Documentation In General
ReadTheDocs - What is it?
ReadTheDocs - Setting up an open source project
Wednesday, October 23, 13
Documentation
How many people document their code?
Why bother?
Wednesday, October 23, 13
DocumentationWhy?
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
DocumentationWhy?
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
DocumentationWhat?
Dependencies
Installation instructions
Guides - like a readme
Things like change logs
Information about supported languages, runtime, and tool versions
Wednesday, October 23, 13
DocumentationWhere?
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
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-writing-great-documentation
Wednesday, October 23, 13
ReadTheDocsFree(!!) 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
ReadTheDocsArchitecture
Wednesday, October 23, 13
Read The Docs
Documentation Start
RTD Setup
RTD Post-Commit Hook
Wednesday, October 23, 13
ReadTheDocsDocumentation Start
$ pip install sphinx$ mkdir docs && cd docs$ sphinx-quickstart
$ make html
Wednesday, October 23, 13
ReadTheDocsRTD Setup
Wednesday, October 23, 13
ReadTheDocsRTD Setup
Wednesday, October 23, 13
ReadTheDocsRTD Setup
Wednesday, October 23, 13
ReadTheDocsRTD Post-Commit Hook
Wednesday, October 23, 13
ReadTheDocsRTD Post-Commit Hook
Wednesday, October 23, 13
ReadTheDocsRTD Post-Commit Hook
Wednesday, October 23, 13
ReadTheDocsPrivate RTD
Can you do it...yes!
Set it up like any other django application stack
Or (beta)
Wednesday, October 23, 13
Things We Didn’t talk about
Sphinx
ReStructuredText(reST)
Documentation Conventions
Wednesday, October 23, 13
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
Resources/References
On Documentation:
http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042
Wednesday, October 23, 13
Resources/References
https://docs.readthedocs.org/en/latest/index.html
http://programmers.stackexchange.com/questions/121775/why-should-you-document-code/121787
http://programmers.stackexchange.com/questions/152325/where-to-put-code-documentation
Wednesday, October 23, 13
Resources/References
http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-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
Thank You!@johncosta
Wednesday, October 23, 13