How to ReadTheDocs
-
Upload
john-costa -
Category
Technology
-
view
498 -
download
0
description
Transcript of How to ReadTheDocs
![Page 1: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/1.jpg)
How to (Really)ReadTheDocs
https://readthedocs.org/ John Costa@johncosta
Wednesday, October 23, 13
![Page 2: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/2.jpg)
About Me
Developer Support Engineer at DotCloud
Introduced to Python through Django when 0.96 was released.
Wednesday, October 23, 13
![Page 3: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/3.jpg)
Overview
Documentation In General
ReadTheDocs - What is it?
ReadTheDocs - Setting up an open source project
Wednesday, October 23, 13
![Page 4: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/4.jpg)
Documentation
How many people document their code?
Why bother?
Wednesday, October 23, 13
![Page 5: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/5.jpg)
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
![Page 6: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/6.jpg)
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
![Page 7: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/7.jpg)
DocumentationWhat?
Dependencies
Installation instructions
Guides - like a readme
Things like change logs
Information about supported languages, runtime, and tool versions
Wednesday, October 23, 13
![Page 8: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/8.jpg)
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
![Page 9: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/9.jpg)
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
![Page 10: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/10.jpg)
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
![Page 11: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/11.jpg)
ReadTheDocsArchitecture
Wednesday, October 23, 13
![Page 12: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/12.jpg)
Read The Docs
Documentation Start
RTD Setup
RTD Post-Commit Hook
Wednesday, October 23, 13
![Page 13: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/13.jpg)
ReadTheDocsDocumentation Start
$ pip install sphinx$ mkdir docs && cd docs$ sphinx-quickstart
$ make html
Wednesday, October 23, 13
![Page 14: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/14.jpg)
ReadTheDocsRTD Setup
Wednesday, October 23, 13
![Page 15: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/15.jpg)
ReadTheDocsRTD Setup
Wednesday, October 23, 13
![Page 16: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/16.jpg)
ReadTheDocsRTD Setup
Wednesday, October 23, 13
![Page 17: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/17.jpg)
ReadTheDocsRTD Post-Commit Hook
Wednesday, October 23, 13
![Page 18: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/18.jpg)
ReadTheDocsRTD Post-Commit Hook
Wednesday, October 23, 13
![Page 19: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/19.jpg)
ReadTheDocsRTD Post-Commit Hook
Wednesday, October 23, 13
![Page 20: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/20.jpg)
ReadTheDocsPrivate RTD
Can you do it...yes!
Set it up like any other django application stack
Or (beta)
Wednesday, October 23, 13
![Page 21: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/21.jpg)
Things We Didn’t talk about
Sphinx
ReStructuredText(reST)
Documentation Conventions
Wednesday, October 23, 13
![Page 22: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/22.jpg)
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
![Page 23: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/23.jpg)
Resources/References
On Documentation:
http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042
Wednesday, October 23, 13
![Page 24: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/24.jpg)
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
![Page 25: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/25.jpg)
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
![Page 26: How to ReadTheDocs](https://reader033.fdocuments.net/reader033/viewer/2022051612/54c2093f4a7959e6068b4628/html5/thumbnails/26.jpg)
Thank You!@johncosta
Wednesday, October 23, 13