Alright, I've been struggling with Sphinx not producing any documentation from the docstrings I've written in this example code. Its a simple implementation of a stack in Python.
You probably need not read all of this:
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:
I've attemped to use Sphinx to document this code with the command $ sphinx-autodoc -o docs/source src/. This outputs the files modules.rst, stack.rst. Then I sphinx-build the output into HTML from my makefile.
My output is a header on an empty page: Stack Module
Is something automatic supposed to be happening here? How do I get any meaningful output from using Sphinx autodoc?
2020-1-31 Update: I'm still having some trouble with this, so I followed the suggestions of Masklinn and created a Github repository in addition to the other suggestion of changing the path as mentioned, but the documentation output is still unsatisfactory.
2020-2-11 Update: The file structure I'm dealing with
.
├── 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
