相关疑难解决方法(0)

我正在尝试使用Sphinx为我的代码库自动生成基本文档.但是,我很难指示Sphinx递归扫描我的文件.

我有一个Python代码库,其文件夹结构如下:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

我运行了sphinx-quickstart <workspace>,所以现在我的结构看起来像:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

我已经阅读了快速入门教程http://sphinx.pocoo.org/tutorial.html,虽然我仍在尝试理解文档,但它的措辞让我担心Sphinx会假设我要手动创建我的代码库中每个模块/类/函数的文档文件.

但是,我确实注意到了"automodule"语句,并且我在快速入门期间启用了autodoc,所以我希望大多数文档都可以自动生成.我修改了我的conf.py来将我的src文件夹添加到sys.path然后修改我的index.rst以使用自动模块.所以现在我的index.rst看起来像:

Contents:

.. toctree::
   :maxdepth: 2

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

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

.. automodule:: alphabuyer
   :members:

我在子包中定义了几十个类和函数.然而,当我跑:

sphinx-build -b html . ./_build

它报道:

updating environment: 1 added, 0 changed, 0 removed

这似乎无法导入我的包内的任何东西.查看生成的index.html在"Contents:"旁边没有显示任何内容.索引页面仅显示"mypackage(模块)",但单击它显示它也没有内容.

如何指导Sphinx递归解析包并自动生成它遇到的每个类/方法/函数的文档,而不必自己手动列出每个类？

pytest建议包含一个额外的目录来分隔项目中的源代码:

my_package
??? src  # <-- no __init__.py on this layer
?   ??? my_package
?       ??? __init__.py
?       ??? util_module
?           ??? __init__.py
?           ??? utils.py
??? tests
    ??? __init__.py
    ??? test_util_module
        ??? __init__.py
        ??? test_utils.py

可悲的是,他们没有说¹关于测试代码中的导入应该如何在这种情况下工作,这对于我的IDE在这个天真的例子^2中工作得很好,但是导致pytest出现以下错误:

my_package $ pytest

====================== test session starts ======================
platform linux -- Python 3.6.4, pytest-3.5.1, py-1.5.3, pluggy-0.6.0
rootdir: /home/user/workspace/my_package, inifile:
collected 0 items / 1 errors     

============================ ERRORS =============================
___ ERROR collecting tests/test_util_module/test_utils.py ___
ImportError while importing test …