chore: switch to mkdocs

.readthedocs.yaml

@@ -1,35 +1,19 @@
-# Read the Docs configuration file for Sphinx projects
+# Read the Docs configuration file for MkDocs projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
+# Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
 
-# Build documentation in the "docs/" directory with Sphinx
-sphinx:
-  configuration: docs/source/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
+mkdocs:
+  configuration: mkdocs.yml
 
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# Optionally declare the Python requirements required to build your docs
 python:
   install:
   - requirements: requirements.txt

docs/.pages

@@ -0,0 +1,7 @@
+nav:
+    - index.md
+    - getting_started.md
+    - faq.md
+    - horde_sdk
+
+order: asc

docs/build_docs.py

@@ -0,0 +1,77 @@
+from pathlib import Path
+
+
+def main() -> None:
+    # Create mkdocs documentation using mkdocstrings
+    project_root = Path(__file__).parent.parent
+    code_root = Path(__file__).parent.parent / "horde_sdk"
+
+    # Get every .py file in the code_root directory and all subdirectories
+    py_files = list(code_root.glob("**/*.py"))
+
+    # Sort the files by path
+    sorted_py_files = sorted(py_files, key=lambda x: str(x))
+
+    pyfile_lookup = convert_list_of_paths_to_namespaces(sorted_py_files, project_root)
+
+    # Get all the folders in code_root and its subdirectories
+    code_root_paths = list(code_root.glob("**/*"))
+    code_root_paths.append(code_root)
+    code_root_paths = [path for path in code_root_paths if path.is_dir()]
+
+    folder_lookup = convert_list_of_paths_to_namespaces(code_root_paths, project_root)
+    # Remove any files from the folder_lookup
+
+    # For each folder in the folder_lookup, create a file in the docs folder
+    for folder, _namespace in folder_lookup.items():
+        relative_folder = folder.relative_to(project_root)
+        relative_folder = "docs" / relative_folder
+        relative_folder.mkdir(parents=True, exist_ok=True)
+
+        with open(relative_folder / ".pages", "w") as f:
+            f.write(f"title: {relative_folder.name}\n")
+
+        # Get all the files in the folder
+        files_in_folder = list(folder.glob("*.py"))
+
+        # Remove any files that start with a dunderscore
+        files_in_folder = [file for file in files_in_folder if "__" not in str(file)]
+
+        # Sort the files by path
+        sorted_files_in_folder = sorted(files_in_folder, key=lambda x: str(x))
+
+        if len(sorted_files_in_folder) == 0:
+            continue
+
+        for file in sorted_files_in_folder:
+            with open(relative_folder / f"{file.stem}.md", "w") as f:
+                f.write(f"# {file.stem}\n")
+                file_namespace = pyfile_lookup[file]
+                f.write(f"::: {file_namespace}\n")
+
+
+def convert_list_of_paths_to_namespaces(paths: list[Path], root: Path) -> dict[Path, str]:
+    # Convert path to string, remove everything in the path before "horde_sdk"
+    lookup = {path: str(path).replace(str(root), "") for path in paths}
+
+    # Remove any entry with a dunderscore
+    lookup = {key: value for key, value in lookup.items() if "__" not in value}
+
+    # If ends in .py, remove that
+    lookup = {key: value[:-3] if value.endswith(".py") else value for key, value in lookup.items()}
+
+    # Replace all slashes with dots
+    lookup = {key: value.replace("\\", ".") for key, value in lookup.items()}
+
+    # Unix paths too
+    lookup = {key: value.replace("/", ".") for key, value in lookup.items()}
+
+    # Remove the first dot
+    lookup = {key: value[1:] if value.startswith(".") else value for key, value in lookup.items()}
+
+    # Purge any empty values
+    return {key: value for key, value in lookup.items() if value}
+
+
+if __name__ == "__main__":
+    main()

docs/faq.md

@@ -0,0 +1,27 @@
+title: Frequently Asked Questions
+
+# Why can't I change an attribute of one of my \*Response or \*Request objects?
+
+> The objects returned by horde_sdk are immutable. If you need to change
+> something, you'll need to create a new object with the changes you
+> want. See [pydantic's
+> docs](https://docs.pydantic.dev/2.0/usage/validation_errors/#frozen_instance)
+> for more information.
+
+# I don't like types. Why is this library so focused on them?
+
+> Types are a great way to ensure that your code is correct. They also
+> make it easier for other developers to understand what your code is
+> doing with [type
+> hints](https://docs.python.org/3/library/typing.html). These *hint*
+> what data format class attributes or functions are expecting or will
+> return. This is how IDEs such as PyCharm or VSCode can provide
+> autocomplete and other helpful features.
+>
+> If you don't like working with the objects within your own code, you
+> can always translate between the types and dicts using pydantic's
+> `.model_dump()` `.model_validate()`. There is also a convenience
+> function
+> `horde_sdk.generic_api.apimodels.HordeAPIModel.to_json_horde_sdk_safe`
+> which may be useful. All API models in this library have this method,
+> but certain other classes may not.

docs/getting_started.md

@@ -0,0 +1,83 @@
+# Getting Started
+
+See `installation` for installation instructions.
+
+## General Notes and Guidance
+
+### Typing
+
+-   Under the hood, **this project is strongly typed**. Practically,
+    this shouldn't leak out too much and should mostly be contained to
+    validation logic.
+    -   If you do find something won't work because of type issues, but
+        you think it should, please [file an issue on
+        github](https://github.com/Haidra-Org/horde-sdk/issues).
+-   This project relies very heavily on [pydantic
+    2.0](https://docs.pydantic.dev/2.0/). If you are unfamiliar with the
+    concepts of pydantic, you may be served by glancing at the
+    documentation for it before consuming this library.
+    -   Every class from this library potentially has validation on its
+        `__init__(...)` function. You should be prepared to handle
+        pydantic's <span class="title-ref">ValidationError</span>
+        exception as a result.
+    -   Most classes from this library have a `model_dump(...)` ([see
+        the
+        doc](https://docs.pydantic.dev/2.0/usage/serialization/#modelmodel_dump))
+        method which will return a dictionary representation of the
+        object if you would rather deal with that than the object
+        itself.
+    -   If you have json or a compatible dict, you can use
+        [model_validate](https://docs.pydantic.dev/2.0/api/main/#pydantic.main.BaseModel.model_validate)
+        or
+        [model_validate_json](https://docs.pydantic.dev/2.0/api/main/#pydantic.main.BaseModel.model_validate_json)
+
+### Inheritance
+
+-   At first glance, the hierarchy of classes may seem a bit confusing.
+    Rest assured, however, that these very docs are very helpful here.
+    All relevant inherited attributes and functions are included in the
+    child class documentation. Accordingly if you are looking at the
+    code, and don't want to go up the hierarchy and figure out the
+    inheritance, use these docs to see the resolved attributes and
+    functions.
+
+### Naming
+
+-   Objects serializable to an API request are suffixed with `Request`.
+-   Objects serializable to an API response are suffixed with
+    `Response`.
+-   Objects which are not meant to be instantiated are prefixed with
+    `Base`.
+    -   These in-between objects are typically logically-speaking parent
+        classes of multiple API objects, but do not represent an actual
+        API object on their own.
+    -   See `horde_sdk.generic_api.apimodels` for some of the key
+        `Base*` classes.
+-   Certain API models have attributes which would collide with a python
+    builtin, such as `id` or `type`. In these cases, the attribute has a
+    trailing underscore, as in `id_`. Ingested json still will work with
+    the field <span class="title-ref">id</span>\` (its a alias).
+
+### Faux Immutability (or 'Why can't I change this attribute?!')
+
+-   All of the \*Request and \*Response class, and many other classes,
+    implement faux immutability, and their attributes are **read only**.
+-   This is to prevent you from side stepping any validation.
+-   See [pydantic's
+    docs](https://docs.pydantic.dev/2.0/usage/validation_errors/#frozen_instance)
+    for more information. See a
+-   See also `faq` for more information.
+
+# Examples
+
+<div class="note" markdown="1">
+
+<div class="title" markdown="1">
+
+Note
+
+</div>
+
+TODO: Add examples
+
+</div>

docs/horde_sdk/.pages

@@ -0,0 +1 @@
+title: horde_sdk

docs/horde_sdk/ai_horde_api/.pages

@@ -0,0 +1 @@
+title: ai_horde_api

docs/horde_sdk/ai_horde_api/ai_horde_client.md

@@ -0,0 +1,2 @@
+# ai_horde_client
+::: horde_sdk.ai_horde_api.ai_horde_client

docs/horde_sdk/ai_horde_api/apimodels/.pages

@@ -0,0 +1 @@
+title: apimodels

docs/horde_sdk/ai_horde_api/apimodels/_stats.md

@@ -0,0 +1,2 @@
+# _stats
+::: horde_sdk.ai_horde_api.apimodels._stats

docs/horde_sdk/ai_horde_api/apimodels/base.md

@@ -0,0 +1,2 @@
+# base
+::: horde_sdk.ai_horde_api.apimodels.base

docs/horde_sdk/ai_horde_api/apimodels/generate/.pages

@@ -0,0 +1 @@
+title: generate

docs/horde_sdk/ai_horde_api/apimodels/generate/_async.md

@@ -0,0 +1,2 @@
+# _async
+::: horde_sdk.ai_horde_api.apimodels.generate._async

docs/horde_sdk/ai_horde_api/apimodels/generate/_check.md

@@ -0,0 +1,2 @@
+# _check
+::: horde_sdk.ai_horde_api.apimodels.generate._check

docs/horde_sdk/ai_horde_api/apimodels/generate/_pop.md

@@ -0,0 +1,2 @@
+# _pop
+::: horde_sdk.ai_horde_api.apimodels.generate._pop

docs/horde_sdk/ai_horde_api/apimodels/generate/_status.md

@@ -0,0 +1,2 @@
+# _status
+::: horde_sdk.ai_horde_api.apimodels.generate._status

docs/horde_sdk/ai_horde_api/apimodels/generate/_submit.md

@@ -0,0 +1,2 @@
+# _submit
+::: horde_sdk.ai_horde_api.apimodels.generate._submit

docs/horde_sdk/ai_horde_api/apimodels/workers/.pages

@@ -0,0 +1 @@
+title: workers

docs/horde_sdk/ai_horde_api/apimodels/workers/_workers_all.md

@@ -0,0 +1,2 @@
+# _workers_all
+::: horde_sdk.ai_horde_api.apimodels.workers._workers_all

docs/horde_sdk/ai_horde_api/consts.md

@@ -0,0 +1,2 @@
+# consts
+::: horde_sdk.ai_horde_api.consts

docs/horde_sdk/ai_horde_api/endpoints.md

@@ -0,0 +1,2 @@
+# endpoints
+::: horde_sdk.ai_horde_api.endpoints

docs/horde_sdk/ai_horde_api/fields.md

@@ -0,0 +1,2 @@
+# fields
+::: horde_sdk.ai_horde_api.fields

docs/horde_sdk/ai_horde_api/metadata.md

@@ -0,0 +1,2 @@
+# metadata
+::: horde_sdk.ai_horde_api.metadata

docs/horde_sdk/ai_horde_worker/.pages

@@ -0,0 +1 @@
+title: ai_horde_worker

docs/horde_sdk/ai_horde_worker/locale_info/.pages

@@ -0,0 +1 @@
+title: locale_info

docs/horde_sdk/consts.md

@@ -0,0 +1,2 @@
+# consts
+::: horde_sdk.consts

docs/horde_sdk/generic_api/.pages

@@ -0,0 +1 @@
+title: generic_api

docs/horde_sdk/generic_api/_reflection.md

@@ -0,0 +1,2 @@
+# _reflection
+::: horde_sdk.generic_api._reflection

docs/horde_sdk/generic_api/apimodels.md

@@ -0,0 +1,2 @@
+# apimodels
+::: horde_sdk.generic_api.apimodels

docs/horde_sdk/generic_api/endpoints.md

@@ -0,0 +1,2 @@
+# endpoints
+::: horde_sdk.generic_api.endpoints

docs/horde_sdk/generic_api/generic_client.md

@@ -0,0 +1,2 @@
+# generic_client
+::: horde_sdk.generic_api.generic_client

docs/horde_sdk/generic_api/metadata.md

@@ -0,0 +1,2 @@
+# metadata
+::: horde_sdk.generic_api.metadata

docs/horde_sdk/generic_api/utils/.pages

@@ -0,0 +1 @@
+title: utils

docs/horde_sdk/generic_api/utils/swagger.md

@@ -0,0 +1,2 @@
+# swagger
+::: horde_sdk.generic_api.utils.swagger

docs/horde_sdk/locales/.pages

@@ -0,0 +1 @@
+title: locales

docs/horde_sdk/localize.md

@@ -0,0 +1,2 @@
+# localize
+::: horde_sdk.localize

docs/horde_sdk/ratings_api/.pages

@@ -0,0 +1 @@
+title: ratings_api

docs/horde_sdk/ratings_api/apimodels.md

@@ -0,0 +1,2 @@
+# apimodels
+::: horde_sdk.ratings_api.apimodels

docs/horde_sdk/ratings_api/endpoints.md

@@ -0,0 +1,2 @@
+# endpoints
+::: horde_sdk.ratings_api.endpoints

docs/horde_sdk/ratings_api/metadata.md

@@ -0,0 +1,2 @@
+# metadata
+::: horde_sdk.ratings_api.metadata

docs/horde_sdk/ratings_api/ratings_client.md

@@ -0,0 +1,2 @@
+# ratings_client
+::: horde_sdk.ratings_api.ratings_client

docs/horde_sdk/scripts/.pages

@@ -0,0 +1 @@
+title: scripts

docs/horde_sdk/scripts/write_all_payload_examples.md

@@ -0,0 +1,2 @@
+# write_all_payload_examples
+::: horde_sdk.scripts.write_all_payload_examples

docs/horde_sdk/scripts/write_all_response_examples.md

@@ -0,0 +1,2 @@
+# write_all_response_examples
+::: horde_sdk.scripts.write_all_response_examples

docs/horde_sdk/utils.md

@@ -0,0 +1,2 @@
+# utils
+::: horde_sdk.utils

docs/index.md

@@ -0,0 +1 @@
+# Home

docs/source/usage.rst → docs/installation.md

@@ -1,13 +1,9 @@
-Usage
-=====
-
-Installation
-------------
+title: Installation
 
 To get started, you need to install the package into your project:
 
-.. code-block:: console
-
-    pip install horde_sdk
+``` console
+pip install horde_sdk
+```
 
 Note that this package requires 3.10 or higher.