Contributing to Django Documentation, Part 1: Generating and Editing Documentation Locally

Posted by: barbara | Date: Sep 12, 2011 | Category: Django    

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:

Contributing to Django

(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:

How to contribute to Django

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:

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.

See also: the Documentation style guide

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