3

好吧，我一直在努力解决 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。然后我sphinx-build从我的makefile输出到HTML。

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

像这个截图

这里应该发生一些自动的事情吗？如何通过使用 Sphinx autodoc 获得任何有意义的输出？

2020-1-31 更新：我还是遇到了一些麻烦，所以我按照 Masklinn 的建议创建了一个Github 存储库，除了上面提到的更改路径的其他建议，但是文档输出仍然不能令人满意。

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
4

0 回答 0