Render API docs (#6463)

* Render API docs

* Cleanup broken links

* Re-enable strict mode

* Change json to yaml

* Update docs/docs/api/schema.md

Co-authored-by: Matthias Mair <code@mjmair.com>

* Update docs/docs/api/schema.md

Co-authored-by: Matthias Mair <code@mjmair.com>

* Use neoteroi-mkdocs instead

- seems to render more reliably

* Fix SERVERS section for SPECTACTULAR_SETTINGS

* Script for splitting schema into smaller sections

* Generate an index file for the schema pages

* Move schema.md up one directory

* Fix formatting

* Remove tracked file

* Add hook for rebuilding API schema as part of RTD build

* Extract schema as RTD build step

* install invoke

* export env vars

* remove argparse

* Fix order of operations

* Compress env vars

* Remove custom env vars

- Now configured as part of RTD project

* Migrate db

* Revert "remove argparse"

This reverts commit 4665805340.

* Post-process generated schema file

* Fix file formatting

* Add note about schema repo

* no message

* Reduce schema overhead

* Ignore generated files

* Delete generated file

* Update .gitignore

* Add extra split for machine integration

* Remove schema files

- These will be auto-generated too

* Generate individual schema .md files

* Re-add .md files

- Need git commit log to work

* Update .gitignore

* Fix for CI test

* patch machine.api

* Revert previous change

* Formatting fix

* Adjust export step

* Bump API version

---------

Co-authored-by: Matthias Mair <code@mjmair.com>

docs/docs/api/api.md

@@ -17,6 +17,17 @@ The API is self-documenting, and the documentation is provided alongside any Inv
 {% include 'img.html' %}
 {% endwith %}
 
+### Schema Description
+    The API schema is also documented in the [API Schema](./schema.md) page.
+
+### Generating Schema File
+
+If you want to generate the API schema file yourself (for example to use with an external client, use the `invoke schema` command. Run with the `-help` command to see available options.
+
+```
+invoke schema -help
+```
+
 ## Authentication
 
 Users must be authenticated to gain access to the InvenTree API. The API accepts either basic username:password authentication, or token authentication. Token authentication is recommended as it provides much faster API access.

docs/docs/api/schema.md

@@ -0,0 +1,40 @@
+---
+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: `171`
+
+!!! tip "API Schema History"
+    We track API schema changes, and provide a snapshot of each API schema version in the [API schema repository](https://github.com/inventree/schema/).
+
+## 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 Machine Management](./schema/machine.md) | External Machine Management |
+| [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/auth.md

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

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

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

docs/docs/api/schema/barcode.md

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

docs/docs/api/schema/bom.md

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

docs/docs/api/schema/build.md

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

docs/docs/api/schema/company.md

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

docs/docs/api/schema/general.md

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

docs/docs/api/schema/label.md

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

docs/docs/api/schema/machine.md

@@ -0,0 +1,7 @@
+---
+title: External Machine Management
+---
+
+The *External Machine Management* section of the InvenTree API schema is documented below.
+
+[OAD(./docs/docs/api/schema/machine.yml)]

docs/docs/api/schema/order.md

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

docs/docs/api/schema/part.md

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

docs/docs/api/schema/plugins.md

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

docs/docs/api/schema/report.md

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

docs/docs/api/schema/settings.md

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

docs/docs/api/schema/stock.md

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

docs/docs/api/schema/user.md

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

docs/docs/concepts/units.md

@@ -48,7 +48,7 @@ The [unit of measure](../part/part.md#units-of-measure) field for the [Part](../
 
 ### Supplier Part
 
-The [supplier part](../part/part/#supplier-parts) model uses real-world units to convert between supplier part quantities and internal stock quantities. Unit conversion rules ensure that only compatible unit types can be supplied
+The [supplier part](../part/part.md/#supplier-parts) model uses real-world units to convert between supplier part quantities and internal stock quantities. Unit conversion rules ensure that only compatible unit types can be supplied
 
 ### Part Parameter
 

docs/docs/extend/plugins/tags.md

@@ -8,7 +8,7 @@ Several models in InvenTree can be tagged with arbitrary tags. Tags are useful f
 Tags are shared between all models that can be tagged.
 
 The following models can be tagged:
-- [Parts](../../part/part.md) and [Supplier Parts](../../order/company#supplier-parts)/[Manufacturer Part](../../order/company#manufacturer-parts)
+- [Parts](../../part/part.md) and [Supplier Parts](../../order/company.md#supplier-parts)/[Manufacturer Part](../../order/company.md#manufacturer-parts)
 - [Stock Items](../../stock/stock.md#stock-item) / [Stock Location](../../stock/stock.md#stock-location)
 
 

docs/docs/part/create.md

@@ -64,6 +64,6 @@ If the *Add Supplier Data* option is checked, then supplier part and manufacture
 
 The following alternative methods for creating parts are supported:
 
-- [Via the REST API](../../api/api)
-- [Using the Python library](../../api/python)
-- [Within the Admin interface](../../settings/admin)
+- [Via the REST API](../api/api.md)
+- [Using the Python library](../api/python/python.md)
+- [Within the Admin interface](../settings/admin.md)

docs/docs/part/notification.md

@@ -7,7 +7,7 @@ title: Part Notifications
 Users can select to receive notifications when certain events occur.
 
 !!! warning "Email Configuration Required"
-    External notifications require correct [email configuration](../../start/config/#email-settings). They also need to be enabled in the settings under notifications`.
+    External notifications require correct [email configuration](../start/config.md#email-settings). They also need to be enabled in the settings under notifications`.
 
 !!! warning "Valid Email Address"
     Each user must have a valid email address associated with their account to receive email notifications
@@ -50,7 +50,7 @@ Any users who are subscribed to notifications for the part in question will rece
 
 ### Build Order Notification
 
-When a new [Build Order](../../build/build/) is created, the InvenTree software checks to see if any of the parts required to complete the order are low on stock.
+When a new [Build Order](../build/build.md) is created, the InvenTree software checks to see if any of the parts required to complete the order are low on stock.
 
 If there are any parts with low stock, a notification is generated for any users subscribed to notifications for the part being built.
 

docs/docs/part/trackable.md

@@ -2,7 +2,7 @@
 title: Trackable Parts
 ---
 
-Denoting a part as *Trackble* changes the way that [stock items](../../stock/stock) associated with the particular part are handled in the database. A trackable part also has more restrictions imposed by the database scheme.
+Denoting a part as *Trackble* changes the way that [stock items](../stock/stock.md) associated with the particular part are handled in the database. A trackable part also has more restrictions imposed by the database scheme.
 
 ## Stock Tracking
 

docs/docs/releases/0.1.5.md

@@ -24,7 +24,7 @@ Refer to the [build documentation](../build/build.md#overdue-builds) for more in
 
 ### Stock Item Expiry
 
-[#1202](https://github.com/inventree/InvenTree/pull/1202) introduces the concept of an *Expiry Date* for Stock Items. For further information, refer to the [expiry documentation](../../stock/expiry).
+[#1202](https://github.com/inventree/InvenTree/pull/1202) introduces the concept of an *Expiry Date* for Stock Items. For further information, refer to the [expiry documentation](../stock/expiry.md).
 
 ### Stock Ownership
 

docs/docs/releases/0.2.1.md

@@ -14,7 +14,7 @@ title: Release 0.2.1
 
 !!! warning "Configuration Required"
     Refer to the [email configuration
-    options](../../start/config/#email-settings).
+    options](../start/config.md#email-settings).
 
 ### Manufacturer Parts
 

docs/docs/releases/0.6.0.md

@@ -54,7 +54,7 @@ PR [#2119](https://github.com/inventree/InvenTree/pull/2119) adds the ability to
 
 ### SSO Support
 
-PR [#2017](https://github.com/inventree/InvenTree/pull/2017) adds support for SSO (single sign on) authentication. SSO integration requires configuration by the system administrator. Refer to the [SSO documentation](../settings/sso) for further information.
+PR [#2017](https://github.com/inventree/InvenTree/pull/2017) adds support for SSO (single sign on) authentication. SSO integration requires configuration by the system administrator. Refer to the [SSO documentation](../settings/SSO.md) for further information.
 
 ### BOM Substitution
 
@@ -74,7 +74,7 @@ PR [#2208](https://github.com/inventree/InvenTree/pull/2208) provides notificati
 
 ### MFA Support
 
-PR [#2221](https://github.com/inventree/InvenTree/pull/2221) adds support for MFA (multi factor authentication). This enables admins to require all users to enable MFA as a second auth step. Refer to the [documentation](../settings/mfa) for further information.
+PR [#2221](https://github.com/inventree/InvenTree/pull/2221) adds support for MFA (multi factor authentication). This enables admins to require all users to enable MFA as a second auth step. Refer to the [documentation](../settings/MFA.md) for further information.
 ### Stock Item Forms
 
 PR [#2198](https://github.com/inventree/InvenTree/pull/2198) provides a major refactor of stock item forms, for creating and editing stock items. These forms have been migrated to the REST API, providing a much more responsive user experience.

docs/docs/stock/owner.md

@@ -33,7 +33,7 @@ When selecting an owner, in the drop-down list, groups are annotated with the <s
 To specify the owner of a stock location, navigate to the stock location detail page. Click on the <span class='fas fa-sitemap'></span> icon under the location's name then click on "Edit Location".
 
 !!! warning
-	If you cannot see the <span class='fas fa-sitemap'></span> icon, it means that you do **not** have permissions to edit stock locations. Refer to [the permissions documentation](../../settings/permissions/#roles) and/or contact your InvenTree administrator.
+	If you cannot see the <span class='fas fa-sitemap'></span> icon, it means that you do **not** have permissions to edit stock locations. Refer to [the permissions documentation](../settings/permissions.md#roles) and/or contact your InvenTree administrator.
 
 In the "Edit Stock Location" form, select the owner and click the "Submit" button:
 
@@ -54,7 +54,7 @@ Setting the owner of stock location will automatically:
 To specify the owner of a stock item, navigate to the stock item detail page. Click on the <span class='fas fa-tools'></span> icon under the item's name then click on "Edit stock item".
 
 !!! warning
-	If you cannot see the <span class='fas fa-tools'></span> icon, it means that you do **not** have permissions to edit stock items. Refer to [the permissions documentation](../../settings/permissions/#roles) and/or contact your InvenTree administrator.
+	If you cannot see the <span class='fas fa-tools'></span> icon, it means that you do **not** have permissions to edit stock items. Refer to [the permissions documentation](../settings/permissions.md/#roles) and/or contact your InvenTree administrator.
 
 In the "Edit Stock Item" form, select the owner and click the "Save" button: