Хорошо, я боролся с 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 вывод в HTML из моего make-файла.
Мой вывод - заголовок на пустой странице: Модуль стека
как этот скриншот
Что-то automati c должно происходить здесь? Как получить какой-либо значимый вывод при использовании Sphinx autodo c?
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