📝 docs update

juftin · Aug 23, 2023 · 58f7d60 · 58f7d60
1 parent 47e856b
commit 58f7d60
Show file tree

Hide file tree

Showing 12 changed files with 277 additions and 1,439 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -29,7 +29,8 @@ repos:
             exclude: |
                 (?x)(
                   .github/semantic_release/release_notes.hbs|
-                  docs/openapi.json
+                  docs/openapi.json|
+                  docs/project_structure.md
                 )
             additional_dependencies:
                 - prettier

diff --git a/docs/clients.md b/docs/clients.md
diff --git a/docs/index.md b/docs/index.md
@@ -15,5 +15,5 @@ and [Alembic](https://alembic.sqlalchemy.org/en/latest/).
 
 -   [Infrastructure :building_construction:](infrastructure.md)
 -   [Contributing :handshake:](contributing.md)
--   [API Clients :computer:](clients.md)
+-   [Project Structure :file_folder:](project_structure.md)
 -   [OpenAPI Docs :sparkles:](openapi.md)
diff --git a/docs/infrastructure.md b/docs/infrastructure.md
@@ -7,25 +7,83 @@ asynchronous web framework for building APIs with Python. FastAPI, in turn, is b
 of [Starlette](https://www.starlette.io/), a lightweight ASGI framework/toolkit, and
 [pydantic](https://docs.pydantic.dev/latest/), a data validation and settings management library.
 
-#### FastAPI
+??? example "FastAPI"
 
-```python
-from fastapi import FastAPI
+    ```python
+    from fastapi import FastAPI
 
-app = FastAPI()
+    app = FastAPI()
 
 
-@app.get("/")
-async def root():
-    return {"message": "Hello World"}
-```
+    @app.get("/")
+    async def root():
+        return {"message": "Hello World"}
+    ```
 
 ### Database ORM
 
-`zoo` uses [SQLModel](https://sqlmodel.tiangolo.com/), a library that provides a declarative
-interface for interacting with databases in Python. SQLModel is built on top
-of [Pydantic](https://pydantic-docs.helpmanual.io/) and
-[SQLAlchemy](https://www.sqlalchemy.org/), a popular SQL toolkit and ORM for Python.
+`zoo` uses [SQLAlchemy 2.0](https://www.sqlalchemy.org/), an Object Relational Mapper (ORM), which means it provides
+a way to interact with databases using Python objects instead of raw SQL. SQLAlchemy 2.0
+is the latest version of SQLAlchemy, which includes support for async/await and the
+latest Python features such as type annotations.
+
+??? example "SQLAlchemy"
+
+    ```python
+    from typing import Optional
+
+    from sqlalchemy import ForeignKey
+    from sqlalchemy.orm import Mapped, mapped_column
+    from sqlalchemy.orm import declarative_base
+
+    Base = declarative_base()
+
+
+    class Hero(Base):
+        """
+        Heroes Database Model
+        """
+
+        __tablename__ = "heroes"
+
+        hero_id: Mapped[int] = mapped_column(primary_key=True)
+        name: Mapped[str]
+        powers: Mapped[Optional[str]] = mapped_column(default=None, nullable=True)
+        secret_identity_id: Mapped[Optional[int]] = mapped_column(ForeignKey("identities.identity_id"),
+                                                                  nullable=True, default=None)
+    ```
+
+### Data Models
+
+`zoo` uses [Pydantic v2](https://docs.pydantic.dev/latest/), a data validation and settings management library.
+Pydantic is used to define the data models for the API endpoints, as well as the
+interface between the API endpoints and the SQLAlchemy ORM models.
+
+??? example "Pydantic"
+
+    ```python
+    from typing import Optional
+
+    from pydantic import BaseModel
+
+
+    class HeroBase(BaseModel):
+        """
+        Hero Base Data Model
+        """
+
+        hero_id: int
+        name: str
+        powers: Optional[str] = None
+        secret_identity_id: Optional[int] = None
+    ```
+
+### API Authentication
+
+`zoo` leverages [fastapi-users](https://frankie567.github.io/fastapi-users/), a high-level library for
+building user authentication on top of FastAPI. fastapi-users provides a set of utilities
+for registering, authenticating, and managing users, as well as a set of endpoints for
+interacting with the user database.
 
 ### Database Migrations
 

diff --git a/docs/openapi.json b/docs/openapi.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "zoo",
-    "description": "### An asynchronous zoo API, powered by FastAPI and SQLModel\n\n[<img src=\"https://raw.githubusercontent.com/juftin/juftin/main/static/juftin.png\" width=\"120\" height=\"120\"  alt=\"juftin logo\">](https://juftin.com)",
+    "description": "### An asynchronous zoo API, powered by FastAPI, SQLAlchemy 2.0, Pydantic v2, and Alembic\n\n[<img src=\"https://raw.githubusercontent.com/juftin/juftin/main/static/juftin.png\" width=\"120\" height=\"120\"  alt=\"juftin logo\">](https://juftin.com)",
     "version": "0.1.0"
   },
   "paths": {

diff --git a/docs/openapi.md b/docs/openapi.md
@@ -2,7 +2,8 @@
 
 ## Interactive Docs
 
-Interactive Swagger docs are available via `/docs` endpoint.
+Interactive Swagger docs are available via `/docs` endpoint of the
+ASGI application.
 
 ```shel
 hatch run app:serve

diff --git a/docs/project_structure.md b/docs/project_structure.md
@@ -0,0 +1,185 @@
+# Project Structure
+
+This project is structured as a Python package. The tree structure is as
+follows (with some files omitted for brevity):
+
+```text
+├── Dockerfile
+├── alembic.ini
+├── docker-compose.yaml
+├── migrations
+│   ├── env.py
+│   ├── script.py.mako
+│   └── versions
+│       └── 2023_08_20_1729-e5fccc3522ce_initial_migration.py
+├── pyproject.toml
+├── requirements.txt
+├── tests
+│   ├── api
+│   │   └── test_animals_api.py
+│   └── conftest.py
+└── zoo
+    ├── __init__.py
+    ├── __main__.py
+    ├── _version.py
+    ├── api
+    │   ├── __init__.py
+    │   └── animals.py
+    ├── app.py
+    ├── config.py
+    ├── db.py
+    ├── models
+    │   ├── __init__.py
+    │   └── animals.py
+    └── schemas
+        ├── __init__.p
+        └── animals.py
+```
+
+## Project Files
+
+-   ??? abstract ":ship: Dockerfile"
+    ```dockerfile
+    --8<-- "Dockerfile"
+    ```
+
+    -   Dockerfile for building the Docker image.
+
+-   ??? abstract ":gear: alembic.ini"
+    ```ini
+    --8<-- "alembic.ini"
+    ```
+
+    -   Configuration file for Alembic project.
+
+-   ??? abstract ":whale: docker-compose.yaml"
+    ```yaml
+    --8<-- "docker-compose.yaml"
+    ```
+
+    -   Docker Compose configuration file for running the application.
+
+-   ??? abstract ":snake: migrations/env.py"
+    ```python
+    --8<-- "migrations/env.py"
+    ```
+
+    -   Configuration file for Alembic migrations to interface with the application
+        database.
+
+-   ??? abstract ":page_facing_up: migrations/script.py.mako"
+    ```python
+    --8<-- "migrations/script.py.mako"
+    ```
+
+    -   Template file for Alembic migrations.
+
+-   ??? abstract ":snake: migrations/versions/2023_08_20_1729-e5fccc3522ce_initial_migration.py"
+    ```python
+    --8<-- "migrations/versions/2023_08_20_1729-e5fccc3522ce_initial_migration.py"
+    ```
+
+    -   Initial migration script generated by Alembic. This is an example of what
+        a migration script looks like - containing an `upgrade` and `downgrade`
+        function.
+
+-   ??? abstract ":gear: pyproject.toml"
+    ```toml
+    --8<-- "pyproject.toml"
+    ```
+
+    -   Configuration file for Python Package and Tooling.
+
+-   ??? abstract ":gear: requirements.txt"
+    ```requirements.txt
+    --8<-- "requirements.txt"
+    ```
+
+    -   Python dependencies for the application. This file is created and managed
+        using [pip-tools](https://pip-tools.readthedocs.io/en/latest/).
+
+-   ??? abstract ":test_tube: tests/api/test_animals_api.py"
+    ```python
+    --8<-- "tests/api/test_animals_api.py"
+    ```
+
+    -   Unit tests for the API endpoints.
+
+-   ??? abstract ":test_tube: tests/conftest.py"
+    ```python
+    --8<-- "tests/conftest.py"
+    ```
+
+    -   Configuration file for pytest. This contains fixtures that are used by the
+        unit tests. This includes a special `client` fixture that is used to
+        perform requests against the application with an ephemeral migrated database.
+
+-   ??? abstract ":snake: zoo/**main**.py"
+    ```python
+    --8<-- "zoo/__main__.py"
+    ```
+
+    -   Command-line entrypoint for the application, built with
+        [click](https://click.palletsprojects.com/). This is
+        used to run the application using `python -m zoo`.
+
+-   ??? abstract ":snake: zoo/\_version.py"
+    ```python
+    --8<-- "zoo/_version.py"
+    ```
+
+    -   Version file for the application. This is used by hatch to
+        set the version of the application.
+
+-   ??? abstract ":snake: zoo/api/animals.py"
+    ```python
+    --8<-- "zoo/api/animals.py"
+    ```
+
+    -   The `api` module contains the API endpoints for the application. This
+        includes the `animals` module, which contains the endpoints for the
+        `/animals` API. These `api` modules contain the relevant FastAPI
+        endpoints, as well as any supporting functions.
+
+-   ??? abstract ":snake: zoo/app.py"
+    ```python
+    --8<-- "zoo/app.py"
+    ```
+
+    -   The `app` module contains the FastAPI application instance. This is
+        where the FastAPI application is created, and where the application
+        dependencies are configured.
+
+-   ??? abstract ":snake: zoo/config.py"
+    ```python
+    --8<-- "zoo/config.py"
+    ```
+
+    -   The `config` module contains the application configuration. This
+        includes the `Settings` class, which is used to configure the
+        application using environment variables.
+
+-   ??? abstract ":snake: zoo/db.py"
+    ```python
+    --8<-- "zoo/db.py"
+    ```
+
+    - The `db` module contains the database configuration. This includes
+        the `SessionLocal` class, which is used to create a SQLAlchemy
+        session for the application.
+
+-   ??? abstract ":snake: zoo/models/animals.py"
+    ```python
+    --8<-- "zoo/models/animals.py"
+    ```
+
+    -   The `models` module contains the SQLAlchemy models for the application.
+
+-   ??? abstract ":snake: zoo/schemas/animals.py"
+    ```python
+    --8<-- "zoo/schemas/animals.py"
+    ```
+
+    -   The `schemas` module contains the Pydantic schemas for the application.
+        These schemas are used to validate the request and response data for the
+        API endpoints.
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -5,8 +5,8 @@ nav:
     - index.md
     - Contributing 🤝: contributing.md
     - Infrastructure 🏗: infrastructure.md
-    - API Clients 💻: clients.md
     - OpenAPI Docs ✨: openapi.md
+    - Project Structure 📂: project_structure.md
 theme:
     favicon: https://raw.githubusercontent.com/juftin/juftin/main/static/juftin.png
     logo: https://raw.githubusercontent.com/juftin/juftin/main/static/juftin.png
@@ -29,6 +29,15 @@ theme:
           toggle:
               icon: material/weather-night
               name: Switch to light mode
+    icon:
+        admonition:
+            abstract: material/file-code
+            tip: material/fire
+            note: fontawesome/regular/note-sticky
+#      note: material/note
+#      note: fontawesome/regular/note-sticky
+#      info: fontawesome/solid/circle-info
+
 repo_url: https://github.com/juftin/zoo
 repo_name: zoo
 edit_uri: blob/main/docs/
@@ -40,7 +49,9 @@ extra:
 markdown_extensions:
     - toc:
           permalink: "#"
-    - pymdownx.snippets
+    - pymdownx.snippets:
+          base_path:
+              - !relative $config_dir
     - pymdownx.magiclink
     - attr_list
     - md_in_html