Expanded documentation (#6)

anton0326 · anton0326 · commit 6a1a54980566 · 2024-09-22T23:06:29.000+01:00
* docs(auth): Updated docs to accommodate auth changes (v0.1.13).

* docs(api): Updated API reference and to pull from codebase.

- Added 'mkdocstrings'
- Changed API page URL from 'lib' -&gt; 'reference'
- Updated mkdocs.yml

* docs(links): Updated page links and error pages.

* ci(workflow): Added CNAME URL.

* docs(api): Split `responses` API reference into separate pages.

* docs(api): Split `auth`, `core` API reference into separate pages.

Plus, updated pages titles for readability.
diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+zentra.achronus.dev
diff --git a/docs/api/lib/auth.md b/docs/api/lib/auth.md
diff --git a/docs/api/lib/core.md b/docs/api/lib/core.md
diff --git a/docs/api/lib/crud.md b/docs/api/lib/crud.md
diff --git a/docs/api/lib/responses.md b/docs/api/lib/responses.md
diff --git a/docs/api/lib/schema.md b/docs/api/lib/schema.md
diff --git a/docs/api/reference/auth/context.md b/docs/api/reference/auth/context.md
@@ -0,0 +1,3 @@
+# zentra_api.auth.context
+
+::: zentra_api.auth.context
diff --git a/docs/api/reference/auth/enums.md b/docs/api/reference/auth/enums.md
@@ -0,0 +1,3 @@
+# zentra_api.auth.enums 
+
+::: zentra_api.auth.enums
diff --git a/docs/api/reference/auth/index.md b/docs/api/reference/auth/index.md
@@ -0,0 +1,3 @@
+# zentra_api.auth
+
+Authentication classes and utilities built into Zentra API. Used in the `auth` routes explored in the [Authentication](../tutorial/authentication.md) tutorial.
diff --git a/docs/api/reference/auth/security.md b/docs/api/reference/auth/security.md
@@ -0,0 +1,3 @@
+# zentra_api.auth.security
+
+::: zentra_api.auth.security
diff --git a/docs/api/reference/core/config.md b/docs/api/reference/core/config.md
@@ -0,0 +1,3 @@
+# zentra_api.core.config
+
+::: zentra_api.core.config
diff --git a/docs/api/reference/core/index.md b/docs/api/reference/core/index.md
@@ -0,0 +1,3 @@
+# zentra_api.core
+
+Configuration classes and utilities unique to Zentra API. Explored in the [Settings](../tutorial/settings.md) tutorial.
diff --git a/docs/api/reference/core/utils.md b/docs/api/reference/core/utils.md
@@ -0,0 +1,3 @@
+# zentra_api.core.utils
+
+::: zentra_api.core.utils
diff --git a/docs/api/reference/crud.md b/docs/api/reference/crud.md
@@ -0,0 +1,5 @@
+# zentra_api.crud
+
+Simple CRUD (create, read, update, delete) operations for interacting with API routes.
+
+::: zentra_api.crud
diff --git a/docs/api/reference/index.md b/docs/api/reference/index.md
@@ -4,4 +4,4 @@ Zentra API comes packed with its own helper methods and classes to really push y
 
 You've already seen a few of these in the [Authentication](../../api/tutorial/authentication.md) tutorial, but that's not all it has to offer!
 
-In this section we focus solely on the extra functionality that the Zentra API package has to offer. 
+In this section we focus solely on the extra functionality that the Zentra API package has to offer.
diff --git a/docs/api/reference/responses/base.md b/docs/api/reference/responses/base.md
@@ -0,0 +1,3 @@
+# zentra_api.responses.base
+
+::: zentra_api.responses.base
diff --git a/docs/api/reference/responses/exceptions.md b/docs/api/reference/responses/exceptions.md
@@ -0,0 +1,3 @@
+# zentra_api.responses.exceptions
+
+::: zentra_api.responses.exceptions
diff --git a/docs/api/reference/responses/index.md b/docs/api/reference/responses/index.md
@@ -0,0 +1,5 @@
+# zentra_api.responses
+
+API response models to use with API routes. See them in action in the [Route Responses](../route-responses.md) tutorial.
+
+::: zentra_api.responses
diff --git a/docs/api/reference/responses/messages.md b/docs/api/reference/responses/messages.md
@@ -0,0 +1,3 @@
+# zentra_api.responses.messages
+
+::: zentra_api.responses.messages
diff --git a/docs/api/reference/responses/models.md b/docs/api/reference/responses/models.md
@@ -0,0 +1,3 @@
+# zentra_api.responses.models
+
+::: zentra_api.responses.models
diff --git a/docs/api/reference/responses/utils.md b/docs/api/reference/responses/utils.md
@@ -0,0 +1,3 @@
+# zentra_api.responses.utils
+
+::: zentra_api.responses.utils
diff --git a/docs/api/reference/schema.md b/docs/api/reference/schema.md
@@ -0,0 +1,8 @@
+# zentra_api.schema
+
+Custom [Pydantic [:material-arrow-right-bottom:]](https://docs.pydantic.dev/latest/) models used throughout the Zentra API package.
+
+::: zentra_api.schema
+    options:
+        members:
+            - Token
diff --git a/docs/api/tutorial/authentication.md b/docs/api/tutorial/authentication.md
@@ -1,12 +1,12 @@
 # User Authentication
 
-Now let's discuss something integral to almost every project: **user authentication**. 
+Now let's discuss something integral to almost every project: **user authentication**.
 
 I can't tell you how many hours we've spent thinking about this topic, mulling over what frameworks to use, how to integrate it with our databases, etc. Talk about boring! 😴
 
 Thankfully, [FastAPI [:material-arrow-right-bottom:]](https://fastapi.tiangolo.com/tutorial/security/) makes it extremely easy, and with Zentra it's straight out of the box! 😍
 
-We abstract a lot of the details away using the [`zentra_api`](../lib/index.md) package to keep things simple for you, but still give you the freedom to configure authentication how you want!
+We abstract a lot of the details away using the [`zentra_api`](../reference/index.md) package to keep things simple for you, but still give you the freedom to configure authentication how you want!
 
 Our authentication files live in the `app/auth` directory, shown below. 
 
diff --git a/docs/help/errors/common.md b/docs/help/errors/common.md
@@ -8,31 +8,31 @@ These types of errors can commonly occur across all commands and packages and ra
 
 You'll encounter this error when the `__init__.py` file is missing from the `zentra/models` directory.
 
-To fix it, run the [`zentra init`](../starting/commands.md#zentra-init) command to create a new `config` file.
+To fix it, run the [`zentra init`](#) command to create a new `config` file.
 
 ## 2: Config File Empty
 
 `Error Code: 2`
 
 You'll encounter this error when the `__init__.py` file in the `zentra/models` directory is empty.
 
-To fix it, run [`zentra init --reset-config`](../starting/commands.md#zentra-init) to create a new one.
+To fix it, run [`zentra init --reset-config`](#) to create a new one.
 
 ## 3: Zentra Directory Missing
 
 `Error Code: 3`
 
 You'll encounter this error when you have the `Zentra` package installed but haven't initialised the project yet.
 
-To fix it, run the [`zentra init`](../starting/commands.md#zentra-init) command.
+To fix it, run the [`zentra init`](#) command.
 
 ## 4: Models Directory Missing
 
 `Error Code: 4`
 
 You'll encounter this error when the `zentra/models` directory is missing.
 
-To fix it, run the [`zentra init`](../starting/commands.md#zentra-init) command.
+To fix it, run the [`zentra init`](#) command.
 
 ## 5: No Components Found
 
@@ -45,12 +45,4 @@ To fix it, open the config file at `zentra/models/__init__.py` and perform the f
 1. `zentra = Zentra()` is initialised
 2. You've registered some `components` or `pages` using `zentra.register()`
 
-If you are still experiencing issues, please reset the config file with [`zentra init --reset-config`](../starting/commands.md#zentra-init).
-
-## 1000: Unknown Error
-
-`Error Code: 1000`
-
-You'll encounter this error when something happens that we haven't accounted for.
-
-For these types of errors, please follow our [Reporting Issues Guide](report.md).
+If you are still experiencing issues, please reset the config file with [`zentra init --reset-config`](#).
diff --git a/docs/help/errors/index.md b/docs/help/errors/index.md
@@ -20,11 +20,13 @@ If you've encountered something extremely mind boggling (trust me, you'll know :
 
 ## Types of Errors
 
-Error messages are split into three main categories:
+!!! construction "Coming Soon"
 
-- [`common`](../errors/common.md) - errors that can occur across all commands and packages. These range between `[1, 10]`
-- [`setup`](../errors/setup.md) - errors specific to the [`init`](#) command. These range between `[11, 20]`.
-- [`build`](../errors/build.md) - errors specific to the [`generate`](#) and [`build`](#) commands. These range between `[21, 30]`.
+<!-- Error messages are split into three main categories: -->
+
+<!-- - [`common`](../errors/common.md) - errors that can occur across all commands and packages. These range between `[1, 10]` -->
+<!-- - [`setup`](../errors/setup.md) - errors specific to the [`init`](#) command. These range between `[11, 20]`. -->
+<!-- - [`build`](../errors/build.md) - errors specific to the [`generate`](#) and [`build`](#) commands. These range between `[21, 30]`. -->
 
 ## 1000: Unknown Error
 
diff --git a/docs/help/errors/setup.md b/docs/help/errors/setup.md
@@ -11,5 +11,5 @@ You'll encounter this error when failing to find the `Zentra` app in `zentra/mod
 To fix it, perform one of the following:
 
 1. If the file exists, initialise `zentra = Zentra()`
-2. Reset the config file with [`zentra init --reset-config`](../starting/commands.md#zentra-init)
+2. Reset the config file with [`zentra init --reset-config`](#)
 
diff --git a/docs/help/index.md b/docs/help/index.md
@@ -4,7 +4,7 @@ This chapter focuses on steps you can take when encountering errors when using o
 
 We've tried to design the error messages to provide you with useful feedback so you can debug and fix most problems yourself.
 
-We know how frustrating errors can be and want to help you focus on programming your project with minimal interference. However, we cannot account for everything. 
+We know how frustrating errors can be and want to help you focus on programming your project with minimal interference. However, we cannot account for everything.
 
 If you need additional information on an error message, we recommend you refer to our [Error Handling Guide](errors/index.md) first.
 
diff --git a/docs/help/report.md b/docs/help/report.md
@@ -0,0 +1,3 @@
+# Reporting Issues
+
+!!! construction "Coming Soon"
diff --git a/docs/models/commands/generate.md b/docs/models/commands/generate.md
@@ -11,4 +11,4 @@ This is the main command you will run when using `Zentra`. It creates and update
 zentra-models generate
 ```
 
-You can read more about it in our [Basic Usage Guide](basic_usage.md#generating-components).
+You can read more about it in our [Basic Usage Guide](#).
diff --git a/docs/models/commands/init.md b/docs/models/commands/init.md
@@ -23,4 +23,4 @@ This requires confirmation to initialise the application and is the recommended
 |`--force`         | removes confirmation requirement. Also, works with `--reset-config`. |
 | `--reset-config` | hard resets the `zentra/models/__init__.py` file. |
 
-You can read more about the [`zentra init`](#zentra-init) command in our [Basic Usage Guide](basic_usage.md#creating-a-project).
+You can read more about the [`zentra init`](#) command in our [Basic Usage Guide](#).
diff --git a/docs/sdk/tutorial/create.md b/docs/sdk/tutorial/create.md
@@ -78,6 +78,6 @@ We'll read more about this in the next chapter, but for now, we should probably
 
 4. Navigate to [http://localhost:3000](http://localhost:3000) and you should see the following:
 
-![Frontend example](/assets/imgs/frontend-startup.jpg)
+![Frontend example](../../assets/imgs/frontend-startup.jpg)
 
 If so, you are good to go! 🚀
diff --git a/docs/templates/partials/version.md b/docs/templates/partials/version.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -59,12 +59,25 @@ nav:
           - Authentication: api/tutorial/authentication.md
           - Project Settings: api/tutorial/settings.md
       - API Reference:
-          - API Reference: api/lib/index.md
-          - zentra_api.auth: api/lib/auth.md
-          - zentra_api.core: api/lib/core.md
-          - zentra_api.crud: api/lib/crud.md
-          - zentra_api.responses: api/lib/responses.md
-          - zentra_api.schema: api/lib/schema.md
+          - API Reference: api/reference/index.md
+          - zentra_api.auth: 
+            - zentra_api.auth: api/reference/auth/index.md
+            - context: api/reference/auth/context.md
+            - enums: api/reference/auth/enums.md
+            - security: api/reference/auth/security.md
+          - zentra_api.core:
+            - zentra_api.core: api/reference/core/index.md
+            - config: api/reference/core/config.md
+            - utils: api/reference/core/utils.md
+          - zentra_api.crud: api/reference/crud.md
+          - zentra_api.responses: 
+            - zentra_api.responses: api/reference/responses/index.md
+            - base: api/reference/responses/base.md  
+            - exceptions: api/reference/responses/exceptions.md
+            - messages: api/reference/responses/messages.md
+            - models: api/reference/responses/models.md
+            - utils: api/reference/responses/utils.md
+          - zentra_api.schema: api/reference/schema.md
       - CLI Commands:
           - CLI Commands: api/commands/index.md
           - init: api/commands/init.md
@@ -79,9 +92,9 @@ nav:
       - Help: help/index.md
       - Errors:
           - Errors: help/errors/index.md
-          - Common Errors: help/errors/common.md
-          - Setup Errors: help/errors/setup.md
-          - Build/Generate Errors: help/errors/build.md
+          # - Common Errors: help/errors/common.md
+          # - Setup Errors: help/errors/setup.md
+          # - Build/Generate Errors: help/errors/build.md
       - Reporting Issues: help/report.md
   - Changelog: changelog.md
 
@@ -119,12 +132,20 @@ markdown_extensions:
       title: Page Contents
 
 plugins:
+  - search
   - mike:
       alias_type: symlink
       canonical_version: latest
-  - search
   - mkdocstrings:
       handlers:
         python:
-          paths: [.]
+          preload_modules:
+            - zentra_api
           options:
+            show_source: true
+            show_root_toc_entry: false
+            show_object_full_path: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            show_object_full_path: false
+            docstring_style: google
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# zentra_api.auth.context`
	`2`	`+`
	`3`	`+::: zentra_api.auth.context`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# zentra_api.auth.enums`
	`2`	`+`
	`3`	`+::: zentra_api.auth.enums`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# zentra_api.auth`
	`2`	`+`
	`3`	+Authentication classes and utilities built into Zentra API. Used in the `auth` routes explored in the [Authentication](../tutorial/authentication.md) tutorial.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# zentra_api.auth.security`
	`2`	`+`
	`3`	`+::: zentra_api.auth.security`