Generate an index file for the schema pages

docs/.gitignore

@@ -10,6 +10,9 @@ env/
 _build/
 site/
 
+# Generated API schema files
+docs/api/schema/*.yml
+
 # Temp files
 releases.json
 versions.json

docs/docs/api/schema.md

@@ -1,13 +0,0 @@
----
-title: API Schema
----
-
-The InvenTree API is implemented using the [Django REST framework](https://www.django-rest-framework.org). The API schema as documented below is generated using the [drf-spectactular](https://github.com/tfranzel/drf-spectacular/) extension.
-
-## Schema File
-
--- TODO -- download
-
-## Schama Spcecification
-
-[OAD(./docs/api.yml)]

docs/docs/api/schema/auth.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Authorization and Authentication API Schema
+    ---
+
+    The *Authorization and Authentication* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/auth.yml)]

docs/docs/api/schema/background-task.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Background Task Management API Schema
+    ---
+
+    The *Background Task Management* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/background-task.yml)]

docs/docs/api/schema/barcode.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Barcode Scanning API Schema
+    ---
+
+    The *Barcode Scanning* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/barcode.yml)]

docs/docs/api/schema/bom.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Bill of Materials API Schema
+    ---
+
+    The *Bill of Materials* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/bom.yml)]

docs/docs/api/schema/build.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Build Order Management API Schema
+    ---
+
+    The *Build Order Management* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/build.yml)]

docs/docs/api/schema/company.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Company Management API Schema
+    ---
+
+    The *Company Management* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/company.yml)]

docs/docs/api/schema/general.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: General API Endpoints API Schema
+    ---
+
+    The *General API Endpoints* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/general.yml)]

docs/docs/api/schema/label.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Label Printing API Schema
+    ---
+
+    The *Label Printing* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/label.yml)]

docs/docs/api/schema/order.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: External Order Management API Schema
+    ---
+
+    The *External Order Management* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/order.yml)]

docs/docs/api/schema/part.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Parts and Part Categories API Schema
+    ---
+
+    The *Parts and Part Categories* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/part.yml)]

docs/docs/api/schema/plugins.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Plugin Functionality API Schema
+    ---
+
+    The *Plugin Functionality* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/plugins.yml)]

docs/docs/api/schema/report.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Report Generation API Schema
+    ---
+
+    The *Report Generation* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/report.yml)]

docs/docs/api/schema/schema.md

@@ -0,0 +1,37 @@
+
+    ---
+    title: InvenTree API Schema
+    ---
+
+    The InvenTree API is implemented using the [Django REST framework](https://www.django-rest-framework.org).
+    The API schema as documented below is generated using the [drf-spectactular](https://github.com/tfranzel/drf-spectacular/) extension.
+
+    ## API Version
+
+    This documentation is for API version: `166`
+
+    ## API Schema File
+
+    The API schema file is available for download, and can be used for generating client libraries, or for testing API endpoints.
+
+    ## API Schema Documentation
+
+    API schema documentation is split into the following categories:
+
+    | Category | Description |
+    | --- | --- |
+    | [Authorization and Authentication](./schema/auth.md) | Authorization and Authentication |
+| [Background Task Management](./schema/background-task.md) | Background Task Management |
+| [Barcode Scanning](./schema/barcode.md) | Barcode Scanning |
+| [Bill of Materials](./schema/bom.md) | Bill of Materials |
+| [Build Order Management](./schema/build.md) | Build Order Management |
+| [Company Management](./schema/company.md) | Company Management |
+| [Label Printing](./schema/label.md) | Label Printing |
+| [External Order Management](./schema/order.md) | External Order Management |
+| [Parts and Part Categories](./schema/part.md) | Parts and Part Categories |
+| [Plugin Functionality](./schema/plugins.md) | Plugin Functionality |
+| [Report Generation](./schema/report.md) | Report Generation |
+| [Settings Management](./schema/settings.md) | Settings Management |
+| [Stock and Stock Locations](./schema/stock.md) | Stock and Stock Locations |
+| [User Management](./schema/user.md) | User Management |
+| [General](./schema/general.md) | General API endpoints |

docs/docs/api/schema/settings.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Settings Management API Schema
+    ---
+
+    The *Settings Management* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/settings.yml)]

docs/docs/api/schema/stock.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: Stock and Stock Locations API Schema
+    ---
+
+    The *Stock and Stock Locations* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/stock.yml)]

docs/docs/api/schema/user.md

@@ -0,0 +1,8 @@
+
+    ---
+    title: User Management API Schema
+    ---
+
+    The *User Management* API schema is documented below.
+
+    [OAD(./docs/docs/api/schema/user.yml)]

docs/exctract_schema.py

@@ -11,22 +11,22 @@ OUTPUT_DIR = './docs/api/schema/'
 GENERAL_PATH = 'general'
 
 # List of special paths we want to split out
-SPECIAL_PATHS = [
+SPECIAL_PATHS = {
-    'auth',
+    'auth': 'Authorization and Authentication',
-    'background-task',
+    'background-task': 'Background Task Management',
-    'barcode',
+    'barcode': 'Barcode Scanning',
-    'bom',
+    'bom': 'Bill of Materials',
-    'build',
+    'build': 'Build Order Management',
-    'company',
+    'company': 'Company Management',
-    'label',
+    'label': 'Label Printing',
-    'order',
+    'order': 'External Order Management',
-    'part',
+    'part': 'Parts and Part Categories',
-    'plugins',
+    'plugins': 'Plugin Functionality',
-    'report',
+    'report': 'Report Generation',
-    'settings',
+    'settings': 'Settings Management',
-    'stock',
+    'stock': 'Stock and Stock Locations',
-    'user',
+    'user': 'User Management',
-]
+}
 
 
 def top_level_path(path: str) -> str:
@@ -43,12 +43,53 @@ def top_level_path(path: str) -> str:
 
     key = path.split('/')[1]
 
-    if key in SPECIAL_PATHS:
+    if key in SPECIAL_PATHS.keys():
         return key
 
     return GENERAL_PATH
 
 
+def generate_index_file(version: str):
+    """Generate the index file for the API schema."""
+    output = f"""
+    ---
+    title: InvenTree API Schema
+    ---
+
+    The InvenTree API is implemented using the [Django REST framework](https://www.django-rest-framework.org).
+    The API schema as documented below is generated using the [drf-spectactular](https://github.com/tfranzel/drf-spectacular/) extension.
+
+    ## API Version
+
+    This documentation is for API version: `{version}`
+
+    ## API Schema File
+
+    The API schema file is available for download, and can be used for generating client libraries, or for testing API endpoints.
+
+    ## API Schema Documentation
+
+    API schema documentation is split into the following categories:
+
+    | Category | Description |
+    | --- | --- |
+    """
+
+    for key, value in SPECIAL_PATHS.items():
+        output += f'| [{value}](./schema/{key}.md) | {value} |\n'
+
+    output += '| [General](./schema/general.md) | General API endpoints |\n'
+
+    output += '\n'
+
+    output_file = os.path.join(os.path.dirname(__file__), OUTPUT_DIR, 'schema.md')
+
+    print('Writing index file to:', output_file)
+
+    with open(output_file, 'w') as f:
+        f.write(output)
+
+
 def parse_api_file(filename: str):
     """Parse the input API file, and split into smaller sections.
 
@@ -88,6 +129,9 @@ def parse_api_file(filename: str):
         with open(output_file, 'w') as f:
             yaml.dump(output, f)
 
+    # Finally, generate an index file for the API schema
+    generate_index_file(data['info']['version'])
+
 
 if __name__ == '__main__':
     parser = argparse.ArgumentParser(description=__doc__)

docs/mkdocs.yml

@@ -183,7 +183,7 @@ nav:
   - Extend:
     - InvenTree API:
       - Overview: api/api.md
-      - Schema: api/schema.md
+      - API Schema: api/schema.md
       - Model Metadata: api/metadata.md
       - Download Data: api/download.md
       - Bulk Delete: api/bulk_delete.md