Contributing to Django Documentation, Part 1: Generating and Editing Documentation Locally
| Django | 2011-09-12 |
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:
/path/to/latest/version/Django-1.3/docs/_build/html
(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:
cd /path/to/latest/version/Django-1.3/docs
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:
vi internals/documentation.txt
(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:
vi index.txt
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