Sphinx autoflask 仅为所有端点制作一页

Question

我继承了一个项目，并且是第一次使用 Sphinx。 我有一个包含所有 api 端点的 app.py，当您制作文档时，您将所有 api.add_resources 包装在一个函数中。

from resources.recipes import GetRecipes, RecipeList, 
from resources.employees import Chefs, Servers, Admin  

def make_port():
   api = Api(app)
   
   api.add_resource(GetRecipes, '/getrecipes/<:string:recipetype>')
   api.add_resource(RecipeList, '/allrecipes/<:string:recipetype>')
   api.add_resource(Chefs, '/chefs/<:string:name>')
   api.add_resource(Servers, '/servers/<:string:name>')
   api.add_resource(Admin, '/admin/<:string:name>') 

   return app

然后我的 app.rst 就在我的文档文件夹中

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

Summary
-------

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

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

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

当我制作文档时，它只制作一个页面，其中包含所有端点。 我尝试过将文件夹“resources/employees, reources/recipes”导入到modules.rst

.. toctree::
   : maxdepth: 4

   app
   resources/employees
   resources/recipes

但结果并不一样。

我想做的是手动组织端点，因为某些端点非常相似，可以组合在一起。

我对这个项目和 sphinx 还很陌生，我无法通过 Sphinx 文档弄清楚它。

Answer 1

我的结构完全错误。

我要做的第一件事就是创建一个文件夹。我将其命名为 api。 我将 app.rst 移至 api 文件夹中，尽管它可以在没有它的情况下构建它。

然后我在 api/.. 文件夹中制作了我想要的页面。

docs
    |_api
         |_recipes.rst
         |_employees.rst

然后我构建了第一个文件夹以包含我想要的该页面的端点。

Employee API
=========

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

Chefs Endpoints
^^^^^^^^^^^^^^^

.. autoflask:: app:make_port()
   :endpoints: Chefs

----
Servers Endpoints
^^^^^^^^^^^^^^^^^^^

.. autoflask:: app:make_port()
   :endpoints: servers

----

Admin Employee Endpoints
^^^^^^^^^^^^^^^^^^^^^

.. autoflask:: app:make_port()
   :endpoints: admin

----

因为我有很多端点，所以我创建了一个 python 脚本，它将采用 txt 文件并为我创建第一个文件。

我创建了一个名为 script 的文件夹，其中包含端点的子目录，并将我的 txt 文件放入其中

docs
    |_api
         |_recipes.rst
         |_employees.rst
    |_scripts
         |_endpoints
                    |_employees.txt
                    |_recipes.txt
         |_endpoint_generator.py

txt 文件只需要将端点放在不同的行上

employees.txt

Chefs
Servers
Admin

如果有人需要的话，这是端点_generator.py。

import os

# Directory containing input text files
input_dir = "endpoints"

# Directory to save generated RST files
output_dir = "../api"

# Check if the input directory exists
if not os.path.exists(input_dir):
    print(f"Error: Directory '{input_dir}' does not exist.")
    exit()

# Create output directory if it doesn't exist
os.makedirs(output_dir, exist_ok=True)

# Get a list of all .txt files in the input directory
input_files = [f for f in os.listdir(input_dir) if f.endswith('.txt')]

# Process each input file
for input_filename in input_files:
    # Construct full path to input file
    input_filepath = os.path.join(input_dir, input_filename)

    # Determine output file name (without extension)
    output_filename = os.path.splitext(input_filename)[0]

    # Read endpoint names from the input file
    endpoints = []
    with open(input_filepath, "r") as f:
        for line in f:
            endpoint = line.strip()
            if endpoint:  # Skip empty lines
                endpoints.append(endpoint.lower())

    # Start building the RST content
    rst_content = ""

    rst_content += f"{output_filename.capitalize()} API\n"
    rst_content += "=" * len(output_filename) + "====\n\n"

    api_table_list = ",".join(str(x) for x in endpoints)
    rst_content += f".. qrefflask:: app:make_port()\n   :endpoints: {api_table_list} \n   :undoc-static:\n\n"

    # Loop through each endpoint
    for endpoint in endpoints:
        # Add section title for the endpoint
        rst_content += f"{endpoint.capitalize()} Endpoints\n"
        rst_content += "^" * len(f"{endpoint} Endpoints") + "\n\n"

        # Add autoflask directive with the endpoint
        rst_content += ".. autoflask:: app:make_port()\n"
        rst_content += f"   :endpoints: {endpoint}\n\n"

        # Add separator after each endpoint except the last one
        if endpoint != endpoints[-1]:
            rst_content += "----\n\n"

    # Construct output file path in the output directory
    output_file_path = os.path.join(output_dir, f"{output_filename}.rst")

    # Write the generated content to the output file
    with open(output_file_path, "w") as f:
        f.write(rst_content)

    print(f"Endpoints RST file '{output_file_path}' generated successfully!")

print("All endpoints RST files generated in directory 'api/'.")

最后我必须编辑添加到页面中的index.rst 文件。

.. toctree::
   :maxdepth: 4

   api/employees
   api/recipes

我希望这对将来的人有帮助！