Sphinx未记录所有类

Question

我正在尝试使用Sphinx来制作我的文档。让我惊讶的是，它对某些类和模块有效，但对其他的却不行。

下面你可以看到一个源文件和一个.rst文件，在这些文件中，Sphinx没有添加我的类。

我使用的是Sphinx的 'sphinx.ext.autodoc' 扩展。

为什么Sphinx没有把我的类添加到文档中？在这种情况下，我该如何调试Sphinx？

我的Sphinx文件：my_project.analyzers.content_ascii.rst

my_project.analyzers.content_ascii package
==========================================

Submodules
----------

my_project.analyzers.content_ascii.wl_redo_detect_date module
--------------------------------------------------------------

.. automodule:: my_project.analyzers.content_ascii.wl_redo_detect_date
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: my_project.analyzers.content_ascii
    :members:
    :undoc-members:
    :show-inheritance:

代码文件：__init__.py

#!/usr/bin/python
# -*- coding: utf-8 -*-
'''
Created on Jan 24, 2014

@author: me
'''

from some_other_project.file_tools import execute_string    
from my_project.analyzers import Analyzer    
from other_project.handler.Handler import Handler

TARGET_ENCODING = 'utf-8'

class ExtractContentAscii(Analyzer):
    '''

    Further improvements: do this and that.
    '''

    def __init__(self):
        Analyzer.__init__(self)

# ...

Answer 1

添加这个元素对我来说非常重要：

:show-inheritance:

如果没有这个，我有两个模块里的类根本没有被识别，还有三个模块里的某些类也莫名其妙地被忽略了。

Answer 2

我发现，要生成文档，Sphinx需要所有的依赖项。并不仅仅是你工作空间里的其他项目，连外部项目也需要在路径中，比如celery或django。

为了解决这个问题：

1) 把你工作空间里的所有依赖项添加到你的路径中，比如在Sphinx的config.py里：

import os
import sys

def add_to_path():

    partial_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), '../../')
    workspace_path = os.path.abspath(partial_path)
    assert os.path.exists(workspace_path)

    projects = []

    for current, dirs, c in os.walk(str(workspace_path)):
        for dir in dirs:

            project_path = os.path.join(workspace_path, dir, 'src')

            if os.path.exists(project_path):
                projects.append(project_path)

    for project_str in projects:
        sys.path.append(project_str)

add_to_path()

2) 确保你需要的外部依赖项都已经在系统上安装好。 处理这些依赖项的一个好方法是使用distutils里的setup.py文件。

3) 构建你的文档

> make clean; make html;

现在你所有的文件应该都能被Sphinx正确地生成文档了。