Sphinx autoflask only makes one page for all the endpoints

Question

I've inherited a project and am using Sphinx for the first time. I've got a app.py that has all my api endpoints and when you make documentation you have all the api.add_resources wrapped in a function.

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

then I have my app.rst in my docs folder

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

Summary
-------

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

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

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

When I make the doc It only makes one single page with all the endpoints on it. I've tried just importing the folder 'resources/employees, recources/recipes into the modules.rst

.. toctree::
   : maxdepth: 4

   app
   resources/employees
   resources/recipes

but it doesn't turn out the same way.

What I'd like to do is organize the endpoints manually as some endpoints are similiar enough to be grouped together.

I'm pretty new to this project and sphinx and I've not been able to figure it out with the Sphinx Documentation.

Answer 1

I had the structure completely wrong.

First thing I had to do was create a folder. I named it api. I moved the app.rst into the api folder though It works building it without it.

Then I made my desired pages inside the api/.. folder.

docs
    |_api
         |_recipes.rst
         |_employees.rst

then I structured the rst folder to have the endpoints I wanted for that page.

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

----

Because I had so many endpoints I make a python script that would take a txt file and create the rst files for me.

I made a folder called scripts with a subdir of endpoints and put my txt files in there

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

the txt file just needs to have the endpoints on different lines

employees.txt

Chefs
Servers
Admin

Here is the endpoint_generator.py if anyone needs it.

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/'.")

and finally I had to edit the index.rst file adding in the pages.

.. toctree::
   :maxdepth: 4

   api/employees
   api/recipes

I hope this helps someone in the future!