使用 Sphinx autodoc 记录 Flask 应用程序答案

【问题标题】：Using Sphinx autodoc to document Flask app使用 Sphinx autodoc 记录 Flask 应用程序
【发布时间】：2017-06-22 10:26:13
【问题描述】：

我在使用 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)

我已经在 venv 中安装了 Sphinx 以及 Web 服务所需的其他包，构建文件夹位于 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'

而且我没有看到我希望为应用程序成员看到的文档，例如请求处理程序和应用程序初始化方法。

我不知道是什么问题，任何帮助将不胜感激。

【问题讨论】：

标签： python-2.7 flask python-sphinx

【解决方案1】：

尝试使用 sphinx-apidoc 自动生成 Sphinx 源，使用 autodoc extension 以其他自动 API 文档工具的样式记录整个包。您还需要将 'sphinx.ext.autodoc' 添加到您的 conf.py 中的 Sphinx 扩展列表中。

【讨论】：