Search code examples
pythondjangodocumentationpython-sphinxsphinx-apidoc

Django Sphinx automodule -- basics

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?

Solution

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

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