Contributing to Django Documentation, Part 1: Generating and Editing Documentation Locally
I just returned from this year's DjangoCon, where there was a lot of buzz around two big topics: managing community and improving documentation.
To that end, I've decided that it's time to start contributing to the Django documentation - documentation, and helping people use it, is a thing about which I am very passionate.
But figuring out how to contribute to an open source project can be a little confusing the first time out, so here are my notes on the process.
You'll want to start with:
(The link to this page appears on the front page of the Django documentation, in the section at the bottom labelled 'The Django open-source project'.)
From that page, there's a link to:
Both pages are worth reading. 'Contributing to Django' is the definitive reference, while 'How to contribute' is more of an FAQ.
And if you're planning to contribute to documentation, there's one more page you'll want to look at:
How the Django documentation works
That in turn refers you to various bits you'll need to know about Sphinx:
- reStructuredText Primer
- Sphinx Markup Constructs
- Module-specific markup
- Inline markup - Cross-referencing documents
If you're relatively new to Sphinx as I am, the markup syntax might be a little confusing. Whether you contribute or not, you'll certainly want to install Sphinx locally and generate the docs yourself. A local version of the docs is useful if you're developing offline. If you're ultimately planning on submitting documentation changes, this is the place to play around with Sphinx markup and test those changes to get a feel for how it works.
So let's start there.
From the "How the Django documentation works" page:
- Building the Django documentation requires Sphinx 1.0.2 or newer. Sphinx also requires the Pygments library for syntax highlighting; building the Django documentation requires Pygments 1.1 or newer (a new-enough version should automatically be installed along with Sphinx).
The best place to get the latest package is PyPI: http://pypi.python.org/pypi/Sphinx.
I like being very hands-on with my installs so I just downloaded the tar (to my /Users/yourusername/InstallPackages folder), unpacked it and ran "python setup.py install". You can of course also use pip. (I should point out that I'm doing this on OS X, although if you've read other posts on this blog you probably already know that.)
[Sphinx-1.0.7]$ sudo python setup.py install
The docs directory will be at the top of your Django version folder (something like /path/to/latest/version/Django-1.3/docs), on the same level as the 'django' folder.
cd /path/to/latest/version/Django-1.3/docs make html
The Django documentation isn't explicit about this, but once Sphinx finishes running, the resulting html files will be at:
(where '/path/to/latest/version/Django-1.3/' is the path to your latest Django version folder)
For the above path, you would load 'file:///path/to/latest/version/Django-1.3/docs/_build/html/index.html' in a browser and navigate around the docs from there. Following the same example path, you'd load 'file:///path/to/latest/version/Django-1.3/docs/_build/html/internals/documentation.html' in a browser to get back to a local version of the 'How the Django documentation works' page.
Once you've gotten this far, it's time to dive in and start making changes.
To find the files you'll actually want to edit, head back up to the top of the docs folder:
You'll see that there's a directory structure mirroring the structure of the documentation:
[docs]$ ls -la drwxr-xr-x 5 barbara barbara 170 Sep 9 17:28 _build drwxr-xr-x@ 10 barbara barbara 340 Mar 22 22:08 faq drwxr-xr-x@ 19 barbara barbara 646 Mar 22 22:08 howto -rw-r--r--@ 1 barbara barbara 7906 Dec 27 2010 index.txt drwxr-xr-x@ 10 barbara barbara 340 Mar 22 22:08 internals drwxr-xr-x@ 11 barbara barbara 374 Mar 22 22:08 intro drwxr-xr-x@ 5 barbara barbara 170 Mar 22 22:08 man drwxr-xr-x@ 6 barbara barbara 204 Mar 22 22:08 misc drwxr-xr-x@ 5 barbara barbara 170 Mar 22 22:08 obsolete drwxr-xr-x@ 22 barbara barbara 748 Mar 22 22:08 ref drwxr-xr-x@ 30 barbara barbara 1020 Mar 22 22:08 releases drwxr-xr-x@ 23 barbara barbara 782 Mar 22 22:08 topics
(There is lots more in that folder - I'm just printing what's relevant here.)
So if you wanted to make a change to the 'How the Django documentation works' page ('file:///path/to/latest/version/Django-1.3/docs/_build/html/internals/documentation.html'), you'd need to open this file:
(Use your editor of choice, of course. Just know that I think you're lame for not using vi.)
Once you open the file, you'll see examples of the Sphinx markup right away. This segment:
Django's documentation uses the Sphinx__ documentation system, which in turn is based on docutils__. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format. __ http://sphinx.pocoo.org/ __ http://docutils.sourceforge.net/
Becomes this when the html is generated:
Django's documentation uses the <a class="reference external" href="http://sphinx.pocoo.org/"> Sphinx</a> documentation system, which in turn is based on <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a>. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format.
Now it's really time to go back and read all that Sphinx markup documentation I linked to above.
Go ahead. I'll wait.
As an example, I'm going to go ahead and make a small change to the front page of the Django documentation (https://docs.djangoproject.com/en/1.3/). On my imaginary system, the file is here:
At the bottom of that file is the link to the documentation page:
* **Documentation:** :doc:`About this documentation <internals/documentation>`
When rendered, the source looks like this:
<li><strong>Documentation:</strong> <a class="reference internal" href="internals/contributing/writing-documentation/"> <em>About this documentation</em></a></li>
I think the link label needs to be edited to make it more clear that this is where you find information about contributing documentation, so I'm going to make a small change to the text:
* **Documentation:** :doc:`About this documentation (and how to contribute to it)<internals/documentation>`
Since I'm already in the docs folder, I'll go ahead and run Sphinx:
[docs]$ make html sphinx-build -b djangohtml -d _build/doctrees . _build/html Running Sphinx v1.0.7 loading pickled environment... done building [djangohtml]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex py-modindex search copying downloadable files... [100%] ref/contrib/gis/create_template_postgis-debian.sh copying static files... done dumping search index... done dumping object inventory... done writing templatebuiltins.js... build succeeded. Build finished. The HTML pages are in _build/html.
Now when I load 'file:///path/to/latest/version/Django-1.3/docs/_build/html/index.html' in my browser, the source reflects the change I just made:
<li><strong>Documentation:</strong> <a class="reference internal" href="internals/documentation.html"> <em>About this documentation (and how to contribute to it)</em></a></li>
And that's it (at least as far as making changes is concerned).
So how do you submit your changes for review and eventually get them into the official Django documentation? That'll be covered next time, in:
Contributing to Django Documentation, Part 2: Submitting A Patch