Initial commit

apps/docs/documentation/configuration/docs.mdx

@@ -0,0 +1,161 @@
+---
+title: Documentation config
+"og:title": Mintlify setup and configuration
+description: Mintlify setup and configuration
+---
+
+## Introduction
+
+The documentation site is built entirely using Mintlify. Mintlify docs are rendered from MDX files and configurations. Mintlify works with a Github integration to
+constantly build an independent docs site based off your latest published repository.
+
+Documentation can be edited in raw MDX, or directly through the Mintlify dashboard (which stays in sync with your local Github repo).
+
+Mintlify is fast to setup and provides tonnes of features out-the-box without the need to pay for a subscription for the basic services.
+
+You can run the **docs site only** by running the `pnpm run dev` command from a terminal within the `docs` directory.
+
+## Docs structure
+
+The docs root directory is structured as follows:
+
+```
+docs
+├── _images
+├── api
+├── configuration
+├── deployment
+├── logos
+├── *.mdx
+├── mint.json
+└── package.json
+```
+
+The docs directory is relatively simple and is made mostly of MDX files. Some notable files are:
+
+| Item         | Description                                                 |
+| ------------ | ----------------------------------------------------------- |
+| api          | Automatically generated files (except for Introduction.mdx) |
+| mint.json    | Mintlify configuration object                               |
+| package.json | Scripts needed in the monorepo/for generating the API files |
+
+## Creating API endpoint documentation
+
+We can leverage FastAPI's baked in OpenAPI support to automatically generate API documentation.
+
+Using Mintlify's `@mintlify/scraping` package, we can scrape our FastAPI's OpenAPI schema to generate an interactive API documentation site.
+
+<Tip>
+  For a more detailed description, read the [official
+  documentation](https://mintlify.com/docs/api-playground/openapi/setup#create-mdx-files-for-openapi-endpoints)
+</Tip>
+
+### Generating OpenAPI schema
+
+#### Step 1: Generate MDX
+
+Run the `generate-api` scripts within the `package.json` to generate the required MDX
+files. There are two scripts here, one configured to use the production
+`OpenAPI.json` and the second configured to use the development version.\
+\
+It is typically preferred to use the production version once any changes to
+your API have been made and published.
+
+#### Step 2: Update mint.json
+
+<Steps>
+  <Step title="Add new MDX files to navigation">
+  Upon generating the relevant API information, `@mintlify/scraping` helpfully outputs the suggested navigation to the terminal:
+
+```bash
+navigation object suggestion:
+[
+  {
+    "group": "users",
+    "pages": [
+      "api/users/get-user",
+      "api/users/get-all-users",
+      "api/users/search-users",
+      "api/users/create-user"
+    ]
+  },
+  {
+    "group": "spells",
+    "pages": [
+      "api/spells/get-spell",
+      "api/spells/get-all-spells",
+      "api/spells/search-spells"
+    ]
+  }
+]
+```
+
+For sake of simplicity, copy this navigation object suggestion and add it your `mint.json` under the `navigation` object:
+
+```json
+"navigation": [
+  {
+    "group": "Getting Started",
+    "pages": ["documentation/introduction", "documentation/local-development"]
+  },
+  {
+    "group": "Configuration",
+    "pages": [
+      "documentation/configuration/turbo",
+      "documentation/configuration/fastapi",
+      "documentation/configuration/nextjs",
+      "documentation/configuration/docs"
+    ]
+  },
+  {
+    "group": "Deployment",
+    "pages": [
+      "documentation/deployment/vercel",
+      "documentation/deployment/deployment"
+    ]
+  },
+  {
+    "group": "API Reference",
+    "pages": ["api/introduction"]
+  },
+  {
+    "group": "Users",
+    "pages": [
+      "api/users/get-user",
+      "api/users/get-all-users",
+      "api/users/search-users",
+      "api/users/create-user"
+    ]
+  },
+  {
+    "group": "Spells",
+    "pages": [
+      "api/spells/get-spell",
+      "api/spells/get-all-spells",
+      "api/spells/search-spells"
+    ]
+  }
+],
+```
+
+  </Step>
+    <Step title="Add OpenAPI endpoint to `mint.json`">
+    Add the `openapi` key to your `mint.json`. This, preferably, can be linked to your published OpenAPI schema:
+
+    ```json
+    {
+      ...
+      "openapi":"https://next-fast-turbo-api.vercel.app/openapi.json"
+      ...
+    }
+    ```
+
+    This enables the generated MDX files to describe and interact with your API.
+
+    <Warning>
+      This has been hit and miss in the past for me. If doing this does not auto-populate your API reference with the documentation, the solution is to manually\
+      create an `openapi.json` file in the `docs` root. Manually copy and paste/save your `openapi.json` into this file.
+    </Warning>
+    </Step>
+
+</Steps>