Sphinx automodule导入失败：Django项目文档生成无内容求助

Let's walk through how to get Sphinx to pull in docstrings from your Django apps instead of just showing the default content. The issue right now is twofold: your current setup isn't loading the Django environment properly for Sphinx, and your index.rst isn't pointing to the actual app modules you want to document.

Step 1: Configure conf.py to Load Django #

Sphinx needs to initialize your Django project to recognize your app modules and their contents. Update your app/docs/source/conf.py with these changes:

import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))

# Initialize Django environment so Sphinx can access your app code
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myapp.settings')
import django
django.setup()

# Enable necessary Sphinx extensions for auto-documentation
extensions = [
    'sphinx.ext.autodoc',       # Core auto-doc extension
    'sphinx.ext.viewcode',      # Add links to source code
    'sphinx.ext.napoleon',      # Support Google/Numpy-style docstrings (optional but useful)
]

# Optional: Set docstring rendering preferences
autodoc_default_options = {
    'members': True,
    'undoc-members': True,      # Include members without docstrings
    'show-inheritance': True,   # Show class inheritance chains
}

Step 2: Restructure Your index.rst and Add App-Specific Docs #

Your current index.rst only references manage.py, which has minimal docstring content. Instead, organize your docs to target each Django app.

Update index.rst #

App's Documentation!
=============================================

Welcome to the full documentation for our Django project. Below you'll find detailed docs for each application:

.. toctree::
   :maxdepth: 2
   :caption: Application Docs:

   authentication
   myapp

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Create App-Specific RST Files #

Make two new files in app/docs/source/:

authentication.rst

Authentication App Documentation
================================

This module handles user authentication and profile management.

.. automodule:: authentication.models
   :members:
   :undoc-members:
   :show-inheritance:

# Uncomment and add other modules as needed
# .. automodule:: authentication.views
#    :members:
#    :undoc-members:
#    :show-inheritance:

myapp.rst

Core Project Configuration
==========================

This module contains the base Django project settings and WSGI configuration.

.. automodule:: myapp.settings
   :members:
   :undoc-members:

.. automodule:: myapp.wsgi
   :members:

Step 3: Ensure Your Code Has Docstrings #

Sphinx can only document code that has docstrings. Add descriptive docstrings to your models, views, and other modules. For example, in authentication/models.py:

from django.db import models
from django.contrib.auth.models import User

class UserProfile(models.Model):
    """
    Extends Django's default User model to store additional user metadata.
    
    Fields:
        user: One-to-one relationship with Django's User model
        bio: Optional text field for user biography
        profile_picture: Optional image field for user profile photos
    """
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    bio = models.TextField(blank=True, max_length=500)
    profile_picture = models.ImageField(upload_to='profile_photos/', blank=True)

    def __str__(self):
        return f"{self.user.username}'s Profile"

Step 4: Regenerate the Documentation #

First clean any old build artifacts to avoid caching issues, then rebuild:

cd app/docs
make clean
make html

Now when you open app/docs/build/html/index.html, you should see your app-specific documentation populated from your code's docstrings.

内容的提问来源于stack exchange，提问作者Anuj TBE