We have no time for creating documentation for our project… wrong! Documentation and tests are crucial in all software projects. Sure, it is more important that our software would work fine but package of unit tests almost always save time (in future as less bugs are produced) and without documentation shouldn’t be treated as “user guide”.
It doesn’t matter if you are creating project for your company or you plan to release it as an open source – by providing documentation you make life easier for other contributors and end-users, of course. And if you know how to write restructuredText documents then you already own necessary skills to create documentation lighting fast!
Prepare!
First of all, you would need to have Distutils and Sphinx installed. You can install it using one of the Python package management tools, in example easy_install would do the job. I prefer to use pip:
pip install distutils
pip install sphinx
Simply use any project you’d like to create documentation for, I would use django-richtemplates. Create a new directory for your documentation and run sphinx-quickstart command:
hg clone https://bitbucket.org/lukaszb/django-richtemplates/ django-richtemplates-temp
cd django-richtemplates-temp
sphinx-quickstart
Just answer some questions – they are very straightforward. You should probably turn autodoc option on.
Sphinx would create some directories for internal usage and static content storage (_build, _static and _templates), configuration file (conf.py) and index file (index.html). Ok, enough of this crap, lets create our first documentation page!
First page
Create new file, lets call it installation.rst and write the document itself:
.. _installation:
============
Installation
============
Fake installation for `django-richtemplates`_ project.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.
.. note::
Yeah, this would be a note.
Very simple, indeed.
Some more crap
--------------
If you would like to highlight a code snippet, it is as easy as::
from mycompany.auth import AuthenticationBackend
class MyClass(object):
"""
Docstring.
"""
def __init__(self, *args, **kwargs):
"""
Some *business* logic.
"""
pass
def authenticate(self, username, password):
"""
External authentication process.
"""
auth = AuthenticationBackend(username, password)
return auth.is_authenticated()
Or choose language explicit:
.. code-block:: bash
cd django-richtemplates
sudo python setup.py install
Yeah, `restructuredText `_ is great!
And easy, too.
External-internal hyperlinks
----------------------------
You may also use ``sphinx`` features, like linking to other *documents*, like
this: go to :ref:`configuration`.
.. _django-richtemplates: http://bitbucket.org/lukaszb/django-richtemplates/
This is standard restructured text document. The only sphinx specific parts are first line (need to add relation with file itself – this is needed for table of contents generation) and reference to other file (which is done with ref:`configuration`). Yup, we haven’t created configuration.rst file, yet. So do this now, and paste following:
.. _configuration:
=========================
Configuring richtemplates
=========================
I hope you have already read chapter :ref:`installation`.
Lorem ipsum!
------------
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur.
Don’t forget about the main page!
I once hoped that the first page (namely index.rst) is generated automatically, yet, I was wrong. But in order
to supply needed data for sphinx generator you have to make very simple changes to the index.rst. Just add
:glob: option to the toctree directive. Finally, mark that all (*) restructuredText documents should
be used.
.. django-richtemplates documentation master file, created by
sphinx-quickstart on Sat Feb 20 21:42:53 2010.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to django-richtemplates's documentation!
================================================
Contents:
.. toctree::
:maxdepth: 2
:glob:
*
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Now in mydocs directory run
make html
and open file located at mydocs/_build/html/index.html. You should see your documentation!
Final words
Ok, this was very simple and the effect is – for such a little work done – quite amazing if you’d ask me.
However, we still haven’t used autodoc Sphinx’s extension. Let’s do that now – create new file
api.rst and paste whats below:
.. _api:
===
API
===
You can find some basic API information here.
Forms API
---------
In this section we cover some basics about the `django-richtemplates`'s forms
API.
.. automodule:: richtemplates.forms
:members:
.. _django-richtemplates: http://bitbucket.org/lukaszb/django-richtemplates/
Again, run make command and see your documentation. Ok, so where is your API, you ask? Well, if you look at the output
of make html command you’d see that there was a warning – richtemplates.forms couldn’t be found.
Which is completely correct, as Sphinx doesn’t try to guess where your modules are, you have to configure it by yourself.
Change sys.path by uncommenting existing line and change it to this:
sys.path.append(os.path.abspath('..'))
If you are not sure why why put .. there, it’s simple – Sphinx would go a one directory up (..) and try to find richtemplates there. Try to build your documentation now. Warning again? Yeah, Sphinx now complains about not
having DJANGO_SETTINGS_MODULE which is, again, totally correct. As importing richtemplates won’t
raise exception, but trying to get deeper into the module (richtemplates.forms) would be impossible without
being within Django context (same would happen if you try to run python interpreter and run from django import forms).
So add this line into your conf.py file:
os.environ['DJANGO_SETTINGS_MODULE'] = 'django.conf.global_settings'
More information about autodoc extension could be found here.
Hope this would help anyone trying to start with his/her own documentation :)
If you have any suggestions – let me know.
Take care and make documentation, not war.
