当源文件不在项目基本文件夹中时，Sphinx入门

Question

[好吧，我一直在为Sphinx苦苦挣扎，无法从我在此示例代码中编写的文档字符串中生成任何文档。它是Python中堆栈的简单实现。

您可能不需要阅读所有这些内容：

src/stack.py

class Stack:
    """Stack
    A simple implementation of a stack data structure in Python.

    """
    def __init__(self):
        self._data = []

    def push(self,item):
        """Push

        Push an item on to the stack.

        Args:
            arg: Item to be pushed to the top of the stack
        """
        self._data.append(item)

    def pop(self):
        """Pop

        Pop the top item off from the stack and return it.

        Returns:
            element: Item at the top of the stack.
        """
        item = self._data[-1]
        self._data = self._data[:-1]
        return item

    def pop_n(self,n):
        """Pop n elements

        Pops the top n elements from the stack.

        Parameters
        ----------
        arg1 : int
            Number of elements to be popped from the top of the stack

        Returns
        -------
        list
            A list of the top n elements popped from the stack
        """
        items = []
        for i in range(0,n):
            items.append(self.pop())
        return items

    def multipop(self):
        """Multipop

        Pops all the elements from the stack

        Returns
        -------
        list
            A list of every element in the stack
        """
        items = []
        while self.size() > 0:
            items.append(self.pop())
        return items

    def size(self):
        """Get Size

        Determine the size of the stack

        Returns
        -------
        int: A count of elements on the stack
        """
        return len(self._data)

conf.py

# sys.path.insert(0, os.path.abspath('../..')) # original path
sys.path.insert(0, os.path.abspath('../src')) # 2020-1-31 edited path

# ... A few inconsequential default settings and author information here ...
extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.coverage',
              'sphinx.ext.napoleon'
             ]

stack.rst

stack module
============

.. automodule:: stack
    :members:
    :undoc-members:
    :show-inheritance:

我已经尝试使用Sphinx通过命令$ sphinx-autodoc -o docs/source src/记录此代码。这将输出文件modules.rst, stack.rst。然后，我从我的makefile sphinx-build输出到HTML。

我的输出是空白页上的标题：堆栈模块

like this screenshot

是否应该在这里发生[[automatic？如何使用Sphinx autodoc获得任何有意义的输出？

2020-1-31更新：我仍然对此有一些麻烦，所以我遵循了Masklinn的建议，并且除了提到的另一条更改路径的建议之外，还创建了一个Github repository，但是文档输出是仍然不能令人满意。

2020-2-11更新：我正在处理的文件结构

.
├── docs
│   ├── build
│   │   ├── doctrees
│   │   │   ├── environment.pickle
│   │   │   ├── index.doctree
│   │   │   ├── modules.doctree
│   │   │   └── src.doctree
│   │   └── html
│   │       └── ... (misc html stuff)
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── modules.rst
│   └── src.rst
├── Readme.md
└── src
    ├── __init__.py
    └── stack.py

Answer 1

这是应用于

当您的源代码位于src之类的Project/src目录而不是简单地位于Project基本目录之内的情况下的“入门”的通常“规范方法”。

执行以下步骤：

1. 在您的docs目录中创建一个Project目录（从该目录中执行以下步骤中的命令）。
2. sphinx-quickstart（从source中选择单独的build）。
3. sphinx-apidoc -o ./source ../src
4. make html

这将产生以下结构（前提是.py源文件位于Project/src中：]

Project
|
├───docs
│   │   make.bat
│   │   Makefile
│   │
│   ├───build
│   └───source
│       │   conf.py
│       │   index.rst
│       │   modules.rst
│       │   stack.rst
│       │
│       ├───_static
│       └───_templates
└───src
        stack.py

在conf.py中，您将添加（在第2步之后：
import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'src')))

也包括在conf.py中：
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
并且在index.rst中，您将链接modules.rst：
Welcome to Project's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules


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

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

您的stack.rst和modules.rst由sphinx-apidoc自动生成，无需更改（此时）。但是只是您知道这就是它们的样子：
stack.rst：
stack module
============

.. automodule:: stack
   :members:
   :undoc-members:
   :show-inheritance:

modules.rst：
src
===

.. toctree::
   :maxdepth: 4

   stack

 
make html在浏览器中打开Project/docs/build/index.html后，结果：
和：

Answer 2

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

这是不正确的。史蒂夫·皮尔西（Steve Piercy）的评论并不完全正确（因为您使用的是简单模块，因此无需添加__init__.py），但它们是对的，自动文档将尝试导入模块然后检查内容。
但是假设您的树是
doc/conf.py
src/stack.py

然后，您只是将包含存储库的文件夹添加到sys.path中，这是完全没有用的。您需要做的是将src文件夹添加到sys.path中，以便在sphinx尝试导入stack时找到您的模块。因此，您的行应为：
sys.path.insert(0, os.path.abspath('../src')

（路径应相对于conf.py）。
注意：由于您具有完全合成的内容，不应包含任何秘密，因此整个内容的可访问存储库或zip文件使诊断问题和提供相关帮助变得更加容易：必须推断的越少，答案中的错误可能更少。