Django Sphinx automodule -- basics

Question

I have a project with several large apps and where settings and apps files are split.

directory structure goes something like that:

project_name

• _init_.py
• apps
• _init_.py
• app1
• app2
• 3rdparty
• _init_.py
• lib1
• lib2
• settings
• _init_.py
• installed_apps.py
• path.py
• templates.py
• locale.py
• ...
• urls.py

every app is like that

• _init_.py
• admin
• _init_.py
• file1.py
• file2.py
• models
• _init_.py
• model1.py
• model2.py
• tests
• _init_.py
• test1.py
• test2.py
• views
• _init_.py
• view1.py
• view2.py
• urls.py

How to use a Sphinx to autogenerate documentation for that?

I want something like that for each in settings module or INSTALLED_APPS (not starting with django.* or 3rdparty.*) give me a auto documentation output based on docstring.

And autogen documentation and run tests before git commit

btw. I tried doing .rst files by hand with

.. automodule:: module_name
   :members:

but is sucks for such a big project, and it does not works for settings

Is there an autogen method or something?

I am not tied to Sphinx, is there a better solution for my problem?

Answer 1

1. See Automatically Generating Documentation for All Python Package Contents.

2. The upcoming Sphinx 1.1 release includes a sphinx-apidoc.py script.

Answer 2

django-sphinx-autodoc will probably be of help here.

From the documentation:

How it works

Copy the generate_autodoc.py file in your project directory, then execute it.

It will scrape all your .py files in each application listed by INSTALLED_APP, then add automodules in your DS_ROOT/modules.rst.

You will then see your applications grouped in 2 different categories:

• internal application is an application located in your project directory
• external application is an app which is somewhere in your pythonpath (preferably in your virtualenv)

Good Practices

Add a docstring in your application's __init__.py file to describe it. django-sphinx-autodoc will automatically scrape it for you.