当源文件不在项目基本文件夹中时，Sphinx入门 [英] Getting started with Sphinx when your source files aren't in the project base folder
问题描述
好的，我一直在为Sphinx苦苦挣扎，因为它无法从我在此示例代码中编写的文档字符串中生成任何文档。它是Python中堆栈的简单实现。
您可能不需要阅读所有内容：
src / stack.py
类堆栈：
堆栈
def __init __（self）：
self._data = []
def push（self） ，item）：
将
推入堆栈。
Args：
arg：要推入的项目
self._data.append（item）
def pop（self）：
Pop
从堆栈中弹出顶部项目并将其返回。
返回：
元素：项目位于堆栈顶部。
item = self._data [-1]
self._data = self._data [：-1]
返回项目
def pop_n（self，n）：
弹出n个元素
弹出sta中的前n个元素ck
参数
----------
arg1：int
从堆栈顶部弹出的元素数
返回
-------
list
从堆栈中弹出的前n个元素的列表
items = [ ]
for i in range（0，n）：
items.append（self.pop（））
返回项目
def multipop（self）：
Multipop
弹出堆栈中的所有元素
返回
-------
列表
堆栈中每个元素的列表
项目= []
，而self.size（）> 0：
items.append（self.pop（ ））
返回项目
def size（self）：
获取大小
确定堆栈的大小
返回
-------
int：el的计数
return len（self._data）
conf.py
＃sys.path.insert（0， os.path.abspath（'../ ..'））＃原始路径
sys.path.insert（0，os.path.abspath（'../ src'））＃2020-1-31编辑路径
＃...一些无关紧要的默认设置和作者信息...
扩展名= ['sphinx.ext.autodoc'，
'sphinx.ext。 coverage，
'sphinx.ext.napoleon'
]
stack.rst
堆栈模块
====== ======
.. automodule :: stack
：members：
：undoc-members：
：show-inheritance：
我尝试使用Sphinx通过命令 $ sphinx-autodoc -o记录此代码docs / source src / 。这将输出文件 modules.rst，stack.rst 。然后，我从makefile sphinx-build 输出到HTML。
我的输出是空白页眉：堆栈模块
< a href = https://i.stack.imgur.com/EkfPw.png rel = nofollow noreferrer>喜欢此屏幕截图
是这里应该发生什么 automatic ？如何使用Sphinx autodoc获得任何有意义的输出？
2020-1-31更新：我仍然遇到一些麻烦，因此我遵循了Masklinn并创建了
并且：
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
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:
这篇关于当源文件不在项目基本文件夹中时，Sphinx入门的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
