错误“表格 主体没有剩余数据，”list-table“指令要求。”同时自动生成Flask应用程序的Sphinx文档

Question

我有像这样的Flask webservice：

from flask import Flask, jsonify
app = Flask(__name__)

@app.route('/api/ping')
def ping():
    """Check if service is alive.

    .. :quickref: Ping; Get pong response
    """
    return jsonify({'status': 'pong!'})

if __name__ == '__main__':
    app.run(host='127.0.0.1', port=8080, debug=True)

我正在使用sphinxcontrib-httpdomain == 1.7.0。我在我的第一个文档中有以下部分，copied from documentation：

Summary
-------

.. qrefflask:: logging_service.main:app

API Details
-----------

.. autoflask:: logging_service.main:app
  :undoc-static:

当我在我的docs文件夹中运行make html时，我收到此错误：

...PROJECT.../docs/logging_service.rst:2: WARNING: Insufficient data supplied (1 row(s)); no data remaining for table body, required by "list-table" directive.

.. list-table::
    :widths: 20 45 35
    :header-rows: 1

    * - Resource
      - Operation
      - Description

我在这里缺少什么？

Answer 1

上述错误通常是由数据丢失引起的。在这种特定情况下，我建议重写服务，例如，以下一种方式：

from flask import Flask, jsonify


def create_app():
    app = Flask(__name__)

    @app.route('/api/ping')
    def ping():
        """Check if service is alive.

        .. :quickref: Ping; Get pong response
        """
        return jsonify({'status': 'pong!'})

    return app


if __name__ == '__main__':
    create_app().run(
        host='127.0.0.1',
        port=8080,
        debug=True
    )

并相应地更新.rst文件：

Summary
-------

.. qrefflask:: logging_service:create_app



API Details
-----------

.. autoflask:: logging_service:create_app
  :undoc-static:

该示例应该有效并希望这将有助于某人理解变更的逻辑。