docs: introduces api reference docs

JacobCoffee · Jun 26, 2023 · b941934 · b941934
2 parents 0f6d4e3 + 93f98b5
commit b941934
Show file tree

Hide file tree

Showing 39 changed files with 522 additions and 15 deletions.
diff --git a/.gitignore b/.gitignore
@@ -104,3 +104,4 @@ coverage.*
 setup.py
 !/niapi/lib/
 !/tests/**/lib/
+!/docs/**/lib/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -24,8 +24,8 @@ repos:
     rev: "1.5.1"
     hooks:
       - id: poetry-check
-      - id: poetry-lock
-        args: ["--no-update"]
+  #      - id: poetry-lock
+  #        args: ["--no-update"]
   - repo: https://github.com/compilerla/conventional-pre-commit
     rev: v2.3.0
     hooks:

diff --git a/docs/api/asgi.rst b/docs/api/asgi.rst
@@ -0,0 +1,8 @@
+====
+asgi
+====
+
+Entry point for ASGI-compatible application.
+
+.. automodule:: niapi.asgi
+     :members:
diff --git a/docs/api/cli.rst b/docs/api/cli.rst
@@ -0,0 +1,16 @@
+===
+cli
+===
+
+Command line interface for the application.
+
+CLI Usage
+---------
+
+.. click:: niapi.cli:run_all_app
+   :prog: run_all_app
+   :nested: full
+
+.. click:: niapi.cli:run_app
+   :prog: app
+   :nested: full
diff --git a/docs/api/domain/calculator/controllers.rst b/docs/api/domain/calculator/controllers.rst
@@ -0,0 +1,8 @@
+===========
+controllers
+===========
+
+Controllers for the application calculator.
+
+.. automodule:: niapi.domain.calculator.controllers
+    :members:
diff --git a/docs/api/domain/calculator/index.rst b/docs/api/domain/calculator/index.rst
@@ -0,0 +1,11 @@
+==========
+calculator
+==========
+
+.. toctree::
+    :titlesonly:
+    :caption: NIAPI Calculator Domain API Reference
+    :glob:
+    :hidden:
+
+    *
diff --git a/docs/api/domain/calculator/schema.rst b/docs/api/domain/calculator/schema.rst
@@ -0,0 +1,8 @@
+======
+schema
+======
+
+Schema for the application calculator.
+
+.. automodule:: niapi.domain.calculator.schema
+    :members:
diff --git a/docs/api/domain/init.rst b/docs/api/domain/init.rst
@@ -0,0 +1,8 @@
+==================
+Domain Initializer
+==================
+
+Initializes the domain module.
+
+.. automodule:: niapi.domain.__init__
+     :members:
diff --git a/docs/api/domain/system/controllers.rst b/docs/api/domain/system/controllers.rst
@@ -0,0 +1,8 @@
+===========
+controllers
+===========
+
+Controllers for the application system.
+
+.. automodule:: niapi.domain.system.controllers
+    :members:
diff --git a/docs/api/domain/system/index.rst b/docs/api/domain/system/index.rst
@@ -0,0 +1,11 @@
+======
+system
+======
+
+.. toctree::
+    :titlesonly:
+    :caption: NIAPI System Domain API Reference
+    :glob:
+    :hidden:
+
+    *
diff --git a/docs/api/domain/urls.rst b/docs/api/domain/urls.rst
@@ -0,0 +1,8 @@
+====
+urls
+====
+
+URL patterns for the NIAPI app.
+
+.. automodule:: niapi.domain.urls
+     :members:
diff --git a/docs/api/domain/web/controllers.rst b/docs/api/domain/web/controllers.rst
@@ -0,0 +1,8 @@
+===========
+controllers
+===========
+
+Controllers for the application web interface.
+
+.. automodule:: niapi.domain.web.controllers.web
+    :members:
diff --git a/docs/api/domain/web/index.rst b/docs/api/domain/web/index.rst
@@ -0,0 +1,11 @@
+===
+web
+===
+
+.. toctree::
+    :titlesonly:
+    :caption: NIAPI Web Domain API Reference
+    :glob:
+    :hidden:
+
+    *
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -1,6 +1,34 @@
+=============
 API Reference
 =============
 
 .. toctree::
     :titlesonly:
-    :maxdepth: 1
+    :caption: API Reference Documentation
+    :glob:
+    :hidden:
+
+    asgi
+    cli
+    metadata
+    utils
+
+.. toctree::
+    :titlesonly:
+    :caption: Domain API Reference
+    :glob:
+    :hidden:
+
+    domain/*
+    domain/web/index
+    domain/system/index
+    domain/calculator/index
+
+.. toctree::
+    :titlesonly:
+    :caption: Library API Reference
+    :glob:
+    :hidden:
+
+    lib/*
+    lib/log/index
diff --git a/docs/api/lib/cors.rst b/docs/api/lib/cors.rst
@@ -0,0 +1,8 @@
+====
+cors
+====
+
+CORS config
+
+.. automodule:: niapi.lib.cors
+     :members:
diff --git a/docs/api/lib/exceptions.rst b/docs/api/lib/exceptions.rst
@@ -0,0 +1,8 @@
+==========
+exceptions
+==========
+
+Application exceptions
+
+.. automodule:: niapi.lib.exceptions
+     :members:
diff --git a/docs/api/lib/log/controller.rst b/docs/api/lib/log/controller.rst
@@ -0,0 +1,9 @@
+==========
+controller
+==========
+
+Log config for the controllers
+
+.. automodule:: niapi.lib.log.controller
+    :members:
+    :noindex:
diff --git a/docs/api/lib/log/index.rst b/docs/api/lib/log/index.rst
@@ -0,0 +1,11 @@
+=======
+logging
+=======
+
+.. toctree::
+    :titlesonly:
+    :caption: Library Logging API Reference Documentation
+    :glob:
+    :hidden:
+
+    *
diff --git a/docs/api/lib/log/init.rst b/docs/api/lib/log/init.rst
@@ -0,0 +1,9 @@
+====
+init
+====
+
+Log initialization
+
+.. automodule:: niapi.lib.log.__init__
+    :members:
+    :noindex:
diff --git a/docs/api/lib/log/utils.rst b/docs/api/lib/log/utils.rst
@@ -0,0 +1,9 @@
+=====
+utils
+=====
+
+Log utils
+
+.. automodule:: niapi.lib.log.utils
+    :members:
+    :noindex:
diff --git a/docs/api/lib/openapi.rst b/docs/api/lib/openapi.rst
@@ -0,0 +1,8 @@
+=======
+openapi
+=======
+
+OpenAPI config
+
+.. automodule:: niapi.lib.openapi
+     :members:
diff --git a/docs/api/lib/schema.rst b/docs/api/lib/schema.rst
@@ -0,0 +1,10 @@
+======
+schema
+======
+
+Schema for the API and application.
+
+
+.. automodule:: niapi.lib.schema
+    :members:
+    :noindex:
diff --git a/docs/api/lib/serialization.rst b/docs/api/lib/serialization.rst
@@ -0,0 +1,8 @@
+=============
+serialization
+=============
+
+Application serialization utilities.
+
+.. automodule:: niapi.lib.serialization
+     :members:
diff --git a/docs/api/lib/settings.rst b/docs/api/lib/settings.rst
@@ -0,0 +1,8 @@
+========
+settings
+========
+
+Application settings
+
+.. automodule:: niapi.lib.settings
+     :members:
diff --git a/docs/api/lib/static_files.rst b/docs/api/lib/static_files.rst
@@ -0,0 +1,8 @@
+============
+static files
+============
+
+Static file config
+
+.. automodule:: niapi.lib.static_files
+     :members:
diff --git a/docs/api/lib/template.rst b/docs/api/lib/template.rst
@@ -0,0 +1,8 @@
+==========
+template
+==========
+
+Template engine config
+
+.. automodule:: niapi.lib.template
+     :members:
diff --git a/docs/api/metadata.rst b/docs/api/metadata.rst
@@ -0,0 +1,8 @@
+========
+metadata
+========
+
+Metadata for the application.
+
+.. automodule:: niapi.metadata
+     :members:
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
@@ -0,0 +1,8 @@
+=====
+utils
+=====
+
+Utilities for the application.
+
+.. automodule:: niapi.utils
+     :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -3,12 +3,17 @@
 
 import importlib.metadata
 import os
+import sys
+from pathlib import Path
 
 from dotenv import load_dotenv
 
 from niapi.metadata import __project__ as project
 
 # -- Environmental Data ------------------------------------------------------
+path = Path("..").resolve()
+tls_verify = False
+sys.path.insert(0, path.as_posix())
 load_dotenv()
 
 # -- Project information -----------------------------------------------------
@@ -41,7 +46,8 @@
     "click": ("https://click.palletsprojects.com/en/8.1.x/", None),
     "structlog": ("https://www.structlog.org/en/stable/", None),
     "opentelemetry": ("https://opentelemetry-python.readthedocs.io/en/latest/", None),
-    "litestar": ("https://docs.litestar.dev/2", None),
+    "litestar": ("https://docs.litestar.dev/2/", None),
+    "msgspec": ("https://jcristharif.com/msgspec/", None),
 }
 
 napoleon_google_docstring = True
@@ -51,13 +57,37 @@
 napoleon_use_admonition_for_references = False
 napoleon_attr_annotations = True
 
-autoclass_content = "class"
-autodoc_class_signature = "separated"
-autodoc_default_options = {"special-members": "__init__", "show-inheritance": True, "members": True}
-autodoc_member_order = "bysource"
-autodoc_typehints_format = "short"
+autoclass_content = "both"
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "exclude-members": "__weakref__",
+    "show-inheritance": True,
+    "class-signature": "separated",
+    "typehints-format": "short",
+}
+
+nitpicky = False  # This is too much of a headache right now
+nitpick_ignore = []
+nitpick_ignore_regex = []
+
+with Path("nitpick-exceptions").open() as file:
+    for line in file:
+        if line.strip() == "" or line.startswith("#"):
+            continue
+        dtype, target = line.split(None, 1)
+        target = target.strip()
+        nitpick_ignore.append((dtype, target))
+
+with Path("nitpick-exceptions-regex").open() as file:
+    for line in file:
+        if line.strip() == "" or line.startswith("#"):
+            continue
+        dtype, target = line.split(None, 1)
+        target = target.strip()
+        nitpick_ignore_regex.append((dtype, target))
 
-nitpicky = True
 autosectionlabel_prefix_document = True
 suppress_warnings = [
     "autosectionlabel.*",