如何配置 Sphinx auto flask 来记录 flask-restful API？答案

【问题标题】：How to configure Sphinx auto flask to document flask-restful API?如何配置 Sphinx auto flask 来记录 flask-restful API？
【发布时间】：2016-05-02 06:26:15
【问题描述】：

我有一个烧瓶应用程序，我想使用 Sphinx 的 autoflask 指令来记录烧瓶休息 API。

https://pythonhosted.org/sphinxcontrib-httpdomain/#module-sphinxcontrib.autohttp.flask

我已经通过 pip 安装了模块并运行 sphinx-quickstart，它给了我一个 conf.py 和 index.rst。

我已经尝试将扩展放入 conf.py：

extensions = ['sphinxcontrib.autohttp.flask']

并根据文档将指令放入 index.rst：

.. autoflask:: autoflask_sampleapp:app
:undos-static:

但我无法正确获取 app:module (autoflask_sampleapp:app) 部分。结果，当我运行 sphinx-build 时，我收到一个错误，即找不到应用程序或模块。

我的应用树如下所示：

.
├── admin
├── apis
├── app
│   ├── static
│   └── templates

从应用的根目录，我可以说：

from apis import profile

如何在 index.rst 中配置 auto flask 以正确查找和加载我的应用的 API 模块？

【问题讨论】：

autoflask_sampleapp 来自哪里？它似乎不在您的“应用程序树”中。

标签： python flask python-sphinx flask-restful

【解决方案1】：

我的代码结构，其中带有烧瓶应用程序的 application.py 文件，我运行我的服务器 python appllication.py runserver

├── application.py
├── _build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│       ├── genindex.html
│       ├── http-routingtable.html
│       ├── index.html
│       ├── objects.inv
│       ├── search.html
│       ├── searchindex.js
│       ├── _sources
│       │   └── index.txt
│       └── _static
├── conf.py
├── index.rst

在 conf.py 中，您应该包含扩展名并包含指向 application.py 或项目中任何其他主要烧瓶应用程序文件的绝对路径。

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinxcontrib.autohttp.flask',
    'sphinxcontrib.autohttp.flaskqref'
]

在您可以使用蓝图后，您的烧瓶应用中的视图

My documentation!
=======================================


.. qrefflask:: application:application
   :undoc-static:

=======================================
Api details!
=======================================

.. autoflask:: application:application
   :undoc-static:

换句话说，在运行 make html 之前，您应该通过 python sys path sys.path.insert(0, os.path.abspath('/home/myproject/')) 将 abs 路径添加到您的根应用程序文件夹， /home/myproject 文件夹与您的源代码。

【讨论】：