Sphinx Auto genrate documentation for Django Project

 

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

Installing your doc directory

python -c 'import sphinx'

If that fails grab the latest version of and install it with:

> sudo easy_install sphinx

Now you are ready to build a template for your docs, using sphinx-quickstart:

> sphinx-quickstart

accepting most of the defaults. I choose “sampledoc” as the name of my project. cd into your new directory and check the contents:

home:~/tmp/sampledoc> ls
Makefile      _static         conf.py
_build                _templates      index.rst

The index.rst is the master ReST for your project, but before adding anything, let’s see if we can build some html:

make html

If you now point your browser to _build/html/index.html, you should see a basic sphinx site.

This will create your basic documentation project. You should have a file layout something like this:

• Makefile   
• _build       
• _static       
• _templates   
• conf.py       
• index.rst
  

.. and you build your documentation simply using the auto-generated build file:
make html

This will now generate a blank skeleton of your documentation ... not really very useful.

Adding some modules

Lets now add some modules for auto-documentation. Lets assume we are have an app called myapp, and we have a models.py module which we want to edit.

In your documentation folder, create a directory called modules, then create a new file called models.rst. e.g.:
mkdir modules
nano modules/models.py

Now edit models.py so that it looks something like this:

myapp.models
==================

.. automodule:: myapp.models
   :members:

now, if we run:
make html

you should get output something like the following:

(test)-bash-3.2$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v0.6.3
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] modules/model                                                                                                                                                                   
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/Me/Projects/MyApp/docs/modules/model.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] modules/model                                                                                                                                                                    
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.

Note the warning in bold. We need to add a link to our documentation from a page. so .. open up index.rst in your documentation root dir, and add something like this:

Modules
==================

.. toctree::
   :maxdepth: 2

   modules/model.rst

running it again, you should now get a new error:

/Users/Me/Projects/MyApp/docs/modules/models.rst:4: (WARNING/2) autodoc can't import/find module 'myapp.model', it reported error: "No module named myapp.model", please check your spelling and sys.path

Configuring your django app

We do as above opening my conf.py file, it now looks something like this:

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append('/Users/Me/Projects/MyApp/src/myapp')
#setup django
import settings
from django.core.management import setup_environ
setup_environ(settings)

.. and finally, we run:
make html

.. and great success, I now have autodocumented modules in my documentation.

For more Detail Click Here