how to readthedocs

How to (Really)ReadTheDocs

https://readthedocs.org/ John Costa@johncosta

Wednesday, October 23, 13

https://readthedocs.org/

https://readthedocs.org/

About Me

Developer Support Engineer at DotCloud

Introduced to Python through Django when 0.96 was released.


Overview

Documentation In General

ReadTheDocs - What is it?

ReadTheDocs - Setting up an open source project


Documentation

How many people document their code?

Why bother?


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


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.


DocumentationWhat?

Dependencies

Installation instructions

Guides - like a readme

Things like change logs

Information about supported languages, runtime, and tool versions


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)


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


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)


ReadTheDocsArchitecture


Read The Docs

Documentation Start

RTD Setup

RTD Post-Commit Hook


ReadTheDocsDocumentation Start

$ pip install sphinx$ mkdir docs && cd docs$ sphinx-quickstart

$ make html


ReadTheDocsRTD Setup


ReadTheDocsRTD Post-Commit Hook


ReadTheDocsPrivate RTD

Can you do it...yes!

Set it up like any other django application stack

Or (beta)


Things We Didn’t talk about

Sphinx

ReStructuredText(reST)

Documentation Conventions


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













On Documentation:

http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042









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



















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/
















Thank You!@johncosta


how to readthedocs

Technology