狮身人面像（文档）应如何与文档字符串一起使用？

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('../..'))
# ... 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获得任何有意义的输出？

Answer 1

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文件使诊断问题和提供相关帮助变得更加容易：必须推断的越少，答案中的错误可能更少。