Jul 11 2011
∞
How to create Sphinx docs the Python / Github / Read the Docs way
This is a full walkthrough of how to document a Python package, using https://github.com/audreyr/django-startcbv as the sample package to be documented. It probably works for non-Python packages too.
Follow along with documenting a Python package of your own. Or try it with one of those poor, undocumented, lonely Python packages out there!
At the command line:
</div><div>pip install Sphinx==1.0.7 (or whatever the latest version is)</div><div>mkdir docs</div><div>cd docs</div><div>sphinx-quickstart</div> <div><div><meta http-equiv="content-type" content="text/html; charset=utf-8">Enter something like the following at the prompts:
</div> <div>> Root path for the documentation [.]: </div></div><div><div>> Separate source and build directories (y/N) [n]: </div></div><div>> Name prefix for templates and static dir [_]: </div><div><div>> Project name: django-startcbv</div> <div>> Author name(s): Audrey Roy</div></div><div><div>> Project version: 0.1</div><div>> Project release [0.1]: </div></div><div><div>> Source file suffix [.rst]:</div></div><div><div>> Name of your master document (without suffix) [index]: </div> </div><div><div>> autodoc: automatically insert docstrings from modules (y/N) [n]: y</div><div>> doctest: automatically test code snippets in doctest blocks (y/N) [n]: </div><div>> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: </div> <div>> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: </div><div>> coverage: checks for documentation coverage (y/N) [n]: </div><div>> pngmath: include math, rendered as PNG images (y/N) [n]: </div> <div>> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: </div><div>> ifconfig: conditional inclusion of content based on config values (y/N) [n]: </div><div>> viewcode: include links to the source code of documented Python objects (y/N) [n]: y</div> </div><div><div>> Create Makefile? (Y/n) [y]: </div><div>> Create Windows command file? (Y/n) [y]: </div></div><div><meta http-equiv="content-type" content="text/html; charset=utf-8"> At the command line:
</div><div>make html</div><div><meta http-equiv="content-type" content="text/html; charset=utf-8">Add to docs/conf.py:
</div><div><div>sys.path.insert(0, os.path.abspath('../startcbv'))</div><div>sys.path.insert(0, os.path.abspath('../test_project'))</div> <div> </div><div>import settings</div><div>from django.core.management import setup_environ</div><div>setup_environ(settings)</div></div><div>Add to your .gitignore file:
</div><div>_templates</div><div>_static</div><div>_build</div></div><div><meta http-equiv="content-type" content="text/html; charset=utf-8">Create docs/ref_startcbv.rst:
</div><div>==========================</div><div>Reference for startcbv app</div> <div>==========================</div><div> </div><div>The startcbv app gives you the management command "python manage.py startcbv things".</div><div> </div><div> </div><div>``startcbv management command``</div> <div>===============================</div><div>.. automodule:: management.commands.startcbv</div><div> :members:</div><div> :undoc-members:</div></div><div><meta http-equiv="content-type" content="text/html; charset=utf-8">Copy and paste your installation and usage instructions from README.rst into docs/installation.rst and docs/usage.rst. I know it’s annoying. There’s no good way to symlink your Github readme content to your Read the Docs Sphinx readme content (yet).
Add to docs/index.rst so that it looks something like:
</div><div><div><div>.. django-startcbv documentation master file, created by</div><div> sphinx-quickstart on Mon Jul 11 21:34:47 2011.</div> <div> You can adapt this file completely to your liking, but it should at least</div><div> contain the root `toctree` directive.</div><div> </div><div>Welcome to django-startcbv's documentation!</div><div>===========================================</div> <div> </div><div>Contents</div><div>-----------</div><div> </div><div>.. toctree::</div><div> :maxdepth: 2</div><div> </div><div> installation</div><div> usage</div><div> </div><div>API/Reference Docs</div> <div>--------------------</div><div> </div><div>.. toctree::</div><div> :maxdepth: 2</div><div> </div><div> ref_startcbv</div><div> </div><div>Indices and tables</div><div>==================</div><div> </div> <div>* :ref:`genindex`</div><div>* :ref:`modindex`</div><div>* :ref:`search`</div></div></div><div>Commit and push it all to Github:
</div><div>cd ~/code/django-startcbv</div> <div>git add .</div><div>git commit -m "Added Sphinx docs."</div><div>git push</div><div>Go to readthedocs.com and create an account.
Enter something like the following:
</div><div>Name: django-startcbv</div> <div>Repo: http://github.com/audreyr/django-startcbv.git</div><div>Repo type: Git</div><div>Description: Management command to start an app with class-based views. You use "python manage.py startcbv ". It's very fresh and unstable, so use at your own risk, but it does work!Project URL: https://github.com/audreyr/django-startcbv</div><div>Tags: ”class-based views”, Django, management</div><div>Default branch: (blank)</div> <div>Use virtualenv: (unchecked)</div><div>Requirements file: (blank)</div><div>Documentation type: Sphinx HTML</div><div>
Click Submit.
Now go to your project on Github (something like https://github.com/audreyr/django-startcbv) and click Admin > Service Hooks > ReadTheDocs. Scroll up. Check “Active”. Click “Update Settings”. From now on, whenever you do a “git push”, your readthedocs.com / rtfd.org docs will be auto-updated.
That’s it. You’re done.
Note: you may have also heard of hosting your docs on http://packages.python.org/. It’s another place to host docs but requires manual updating by the PyPI staff. Personally, I like using ReadTheDocs instead, though, because:
- the Github hooks keep my docs up-to-date without manual intervention. Whenever I update my .rst files, I don’t have to re-upload my docs!
- the docs are easier to find via search engines
Finally, whenever you do something complicated without documenting it, imagine the documentation donkey (a cross between the Django pony and the Shrek donkey) kicking you the next time you can’t figure out how to retrace your steps.
