如何通过Sphinx Autoflask手动分组Flask API端点文档？

问题场景 #

你的app.py中所有API端点注册逻辑都封装在make_port()函数里，当前用autoflask生成的文档会把所有端点堆在同一页面，希望按业务逻辑（比如食谱、员工）手动分组展示。

解决步骤 #

1. 创建分组专用的RST文档 #

在文档目录下新建两个文件，分别对应不同业务组：

recipes_api.rst（食谱相关端点）

食谱相关API
===========

.. autoflask:: app:make_port()
   :endpoints: GetRecipes, RecipeList
   :undoc-static:

employees_api.rst（员工相关端点）

员工管理API
===========

.. autoflask:: app:make_port()
   :endpoints: Chefs, Servers, Admin
   :undoc-static:

2. 更新目录结构（modules.rst） #

修改modules.rst的toctree，将新创建的分组文档加入，替换原来的resources/employees和resources/recipes：

.. toctree::
   :maxdepth: 4

   app
   recipes_api
   employees_api

3. 调整主API文档（app.rst） #

保留总览部分，将详细分组的内容替换为指向新页面的链接，让用户可以从总览跳转到对应分组：

API Documentation
=================

Summary
-------

.. qrefflask:: app:make_port()
    :undoc-static:

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

- :doc:`recipes_api`：食谱查询相关接口
- :doc:`employees_api`：员工管理相关接口

关键注意事项 #

• 确保autoflask的:endpoints参数值和你app.py中导入的类名完全一致（比如类是GetRecipes，就不能写成getRecipes，大小写敏感）
• 每个autoflask块只包含对应分组的端点，实现精准分组
• :undoc-static:参数保持不变，避免生成静态文件的无关文档

内容的提问来源于stack exchange，提问作者jeffyd193