Django app/models.py 的 Sphinx-apidoc 奇怪输出

Question

我在 django 项目的生成文档中得到了一些遗漏的信息，例如 first_name 和 last_name、email 被遗漏了（尽管它们是在父摘要中定义的 class).如何控制基于 sphinx-apidoc 扫描添加到文档中的内容？我的目标是根据文档自动生成文档，但似乎 sphinx-apidoc 应该只用于初始脚手架

我尝试使用 :inherited-members: 如下所示，但它仍然没有生成 first_name、last_name 中存在的电子邮件AbstractUserclass

.. automodule:: apps.users.models
    :members:
    :inherited-members:
    :show-inheritance:

我执行以下命令

sphinx-apidoc -f -e -d 2 -M -o docs/code apps '*tests*' '*migrations*'

输出

我的apps/users/models.py

from django.contrib.auth.models import AbstractUser
from django.contrib.postgres.fields import HStoreField
from imagekit import models as imagekitmodels
from imagekit.processors import ResizeToFill

from libs import utils

# Solution to avoid unique_together for email
AbstractUser._meta.get_field('email')._unique = True


def upload_user_media_to(instance, filename):
    """Upload media files to this folder"""
    return '{}/{}/{}'.format(instance.__class__.__name__.lower(), instance.id,
                             utils.get_random_filename(filename))


__all__ = ['AppUser']


class AppUser(AbstractUser):
    """Custom user model.

    Attributes:
        avatar (file): user's avatar, cropeed to fill 300x300 px
        notifications (dict): settings for notifications to user
    """

    avatar = imagekitmodels.ProcessedImageField(
        upload_to=upload_user_media_to,
        processors=[ResizeToFill(300, 300)],
        format='PNG',
        options={'quality': 100},
        editable=False,
        null=True,
        blank=False)

    notifications = HStoreField(null=True)

    # so authentication happens by email instead of username
    # and username becomes sort of nick
    USERNAME_FIELD = 'email'

    # Make sure to exclude email from required fields if authentication
    # is done by email
    REQUIRED_FIELDS = ['username']

    def __str__(self):
        return self.username

    class Meta:
        verbose_name = 'User'
        verbose_name_plural = 'Users'

我的狮身人面像conf.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import os
import sys

import django
import sphinx_py3doc_enhanced_theme

sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('.'))
os.environ.setdefault(
    "DJANGO_SETTINGS_MODULE", "config.settings.local")
django.setup()

# Extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinxcontrib.blockdiag'
]

napoleon_google_docstring = True
napoleon_use_param = True
napoleon_use_ivar = False
napoleon_use_rtype = True
napoleon_include_special_with_doc = False

# RST support
source_suffix = '.rst'

# Name of master doc
master_doc = 'index'

# General information about the project.
project = 'crm'
copyright = '2017, Company'
author = 'Company'


version = '0.1'

release = '0.1'

language = None

exclude_patterns = []

todo_include_todos = False

# Read the docs theme
html_theme = 'sphinx_py3doc_enhanced_theme'
html_theme_path = [sphinx_py3doc_enhanced_theme.get_html_theme_path()]

html_static_path = []

htmlhelp_basename = 'crmdoc'

latex_elements = {}


# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'crm', 'crm Documentation',
     [author], 1)
]

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (master_doc, 'crm', 'crm Documentation',
     author, 'crm', 'One line description of project.',
     'Miscellaneous'),
]

html_theme_options = {
    'githuburl': 'https://github.com/ionelmc/sphinx-py3doc-enhanced-theme/',
    'bodyfont': '"Lucida Grande",Arial,sans-serif',
    'headfont': '"Lucida Grande",Arial,sans-serif',
    'codefont': '"Deja Vu Sans Mono",consolas,monospace,sans-serif',
    'linkcolor': '#0072AA',
    'visitedlinkcolor': '#6363bb',
    'extrastyling': False,
    'sidebarwide': True

}
pygments_style = 'friendly'

html_context = {
    'css_files': ['_static/custom.css'],
}

Answer 1

好吧，结果我不得不使用 :undoc-members:，但它造成了混乱。

这是必需的，因为 django 的 AbstractUser class 没有正确记录，并且必须强制 sphinx 显示仅定义了 undoc-members 的字段。但是 undoc-members 造成了混乱，所以解决方案只是在子 class 的 docstr 中为 attributes/methods 添加在父 class 中没有记录的文档，之后我的文档得到了显示这些字段

class AppUser(AbstractUser):
    """Custom user model.

    Attributes:
        avatar (file): user's avatar, cropeed to fill 300x300 px
        notifications (dict): settings for notifications to user
        first_name (str): first name
        last_name (str): last name
    """

Django app/models.py 的 Sphinx-apidoc 奇怪输出

Sphinx-apidoc strange output for django app/models.py

django

python-3.x

python-sphinx

sphinx-apidoc

我执行以下命令

输出

我的apps/users/models.py

我的狮身人面像conf.py