Ошибка «нет данных для тела таблицы, что требуется директивой list-table». во время автогенерации документации Sphinx для приложения Flask

Question

У меня есть веб-сервис Flask:

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. И у меня есть следующие разделы в моих первых документах, скопированные из документации :

Summary
-------

.. qrefflask:: logging_service.main:app

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

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

Когда я запускаю 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:

Пример должен сработать и надеяться, что это поможет кому-то понять логику изменений.