django sphinx automodule — basics [closed]

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.