问题
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
like this screenshot
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
回答1:
This is the usual "canonical approach" to "getting started" applied to the case when your source code resides in a src directory like Project/src instead of simply being inside the Project base directory.
Follows these steps:
Create a
docsdirectory in yourProjectdirectory (it's from this directory the commands in the following steps are executed).sphinx-quickstart(choosing separatesourcefrombuild).sphinx-apidoc -o ./source ../srcmake html
This would yield the following structure (provided you .py source files reside in Project/src):
Project
|
├───docs
│ │ make.bat
│ │ Makefile
│ │
│ ├───build
│ └───source
│ │ conf.py
│ │ index.rst
│ │ modules.rst
│ │ stack.rst
│ │
│ ├───_static
│ └───_templates
└───src
stack.py
In your conf.py you'd add (after step 2):
import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'src')))
Also include in conf.py:
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
And in index.rst you'd link modules.rst:
Welcome to Project's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Your stack.rst and modules.rst were auto-generated by sphinx-apidoc, no need to change them (at this point). But just so you know this is what they look like:
stack.rst:
stack module
============
.. automodule:: stack
:members:
:undoc-members:
:show-inheritance:
modules.rst:
src
===
.. toctree::
:maxdepth: 4
stack
After
make html open Project/docs/build/index.html in your browser, the results:
and:
回答2:
sys.path.insert(0, os.path.abspath('../..'))
That's not correct. Steve Piercy's comment is not entirely on point (you don't need to add a __init__.py since you're using a simple module) but they're right that autodoc will try to import the module and then inspect the content.
Hoever assuming your tree is
doc/conf.py
src/stack.py
then you're just adding the folder which contains your repository to the sys.path which is completely useless. What you need to do is add the src folder to sys.path, such that when sphinx tries to import stack it finds your module. So your line should be:
sys.path.insert(0, os.path.abspath('../src')
(the path should be relative to conf.py).
Of note: since you have something which is completely synthetic and should contain no secrets, an accessible repository or a zip file of the entire thing makes it much easier to diagnose issues and provide relevant help: the less has to be inferred, the less can be wrong in the answer.
来源：https://stackoverflow.com/questions/59995388/getting-started-with-sphinx-when-your-source-files-arent-in-the-project-base-fo