我在使用Sphinx为Flask应用程序生成文档时遇到了问题。不详细介绍应用程序的特定细节,其基本结构如下所示。
__all__ = ['APP']
<python 2 imports>
<flask imports>
<custom imports>
APP = None # module-level variable to store the Flask app
<other module level variables>
# App initialisation
def init():
global APP
APP = Flask(__name__)
<other initialisation code>
try:
init()
except Exception as e:
logger.exception(str(e))
@APP.route(os.path.join(<service base url>, <request action>), methods=["POST"])
<request action handler>
if __name__ == '__main__':
init()
APP.run(debug=True, host='0.0.0.0', port=5000)
我已经在虚拟环境中安装了Sphinx以及其他Web服务所需的软件包,build文件夹位于docs子文件夹中,如下所示。
docs
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── introduction.rst
└── make.bat
conf.py
是通过运行 sphinx-quickstart
生成的,其中包含以下行:
autodoc_mock_imports = [<external imports to ignore>]
为确保Sphinx忽略列出的外部导入内容。
index.rst
是标准格式。.. myapp documentation master file, created by
sphinx-quickstart on Fri Jun 16 12:35:40 2017.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to myapp's documentation!
=============================================
.. toctree::
:maxdepth: 2
:caption: Contents:
introduction
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
我已经添加了一个introduction.rst
页面来记录应用程序成员的信息。
===================
`myapp`
===================
Oasis Flask app that handles keys requests.
myapp.app
---------------------
.. automodule:: myapp.app
:members:
:undoc-members:
当我在
docs
目录下运行make html
时,会在_build
子文件夹中获得HTML输出,但是我收到了以下警告信息。WARNING: /path/to/myapp/docs/introduction.rst:10: (WARNING/2) autodoc: failed to import module u'myapp.app'; the following exception was raised:
Traceback (most recent call last):
File "/path/to/myapp/venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 657, in import_object
__import__(self.modname)
File "/path/to/myapp/__init__.py", line 4, in <module>
from .app import APP
File "/path/to/myapp/app.py", line 139, in <module>
@APP.route(os.path.join(<service base url>, <request action>), methods=['GET'])
File "/path/to/myapp/venv/lib/python2.7/posixpath.py", line 70, in join
elif path == '' or path.endswith('/'):
AttributeError: 'NoneType' object has no attribute 'endswith'
我没有看到我期望看到的应用程序成员文档,如请求处理程序和应用程序初始化方法。
我不知道问题出在哪里,任何帮助都将不胜感激。