feat(docs): Add library documentation

docs/index.md

@@ -0,0 +1,23 @@
+# PyVolt
+
+Welcome to PyVolt! PyVolt is a simple and flexible wrapper for [Revolt.chat](https://revolt.chat) built to be fast and reliable.
+
+## Key features
+
+- Built on [Python](https://python.org)'s `asyncio` library.
+- Sane rate limit handling built to prevent 429s.
+- Efficient memory usage.
+- A customizable architecture built to be rewritten.
+- Focus on supporting both **bots** and **users** accounts.
+
+## Installation
+
+!!! note
+
+    Currently PyVolt only supports installing via Git, in the future we plan to add [PyPI](https://pypi.org) as a distributor.
+
+### GitHub :fontawesome-brands-github:
+
+``` bash title="Bash"
+pip install https://github.com/MCausc78/pyvolt.git@master
+```

docs_requirements.txt

@@ -0,0 +1,6 @@
+mkdocs>=1.6.1
+mkdocs-material>=9.5.47
+mkdocstrings-python>=1.12.2
+mkdocs-gen-files==0.5.0
+mkdocs-literate-nav==0.6.1
+griffe-inherited-docstrings==1.1.1

mkdocs.yml

@@ -0,0 +1,106 @@
+site_name: PyVolt Documentation
+
+theme:
+  name: material
+
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: pink
+      accent: deep purple
+      toggle:
+        icon: material/lightbulb
+        name: Switch to dark mode
+
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: pink
+      accent: deep purple
+      toggle:
+        icon: material/lightbulb-outline
+        name: Switch to light mode
+
+  features:
+    - content.code.copy
+    - content.tabs.link
+    - search.highlight
+    - search.suggest
+    - search.share
+    - content.action.edit
+    - navigation.tabs
+    - navigation.indexes
+    - navigation.top
+    - toc.follow
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - meta
+  - md_in_html
+  - toc:
+      permalink: "#"
+
+  # Python Markdown Extensions
+  - pymdownx.snippets
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.superfences
+  - pymdownx.tilde
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.tabbed:
+      alternate_style: true
+      combine_header_slug: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+
+
+
+plugins:
+  - mkdocstrings:
+      enabled: !ENV [ENABLE_MKDOCSTRINGS, true]
+      default_handler: python
+      enable_inventory: true
+      handlers:
+        python:
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://docs.aiohttp.org/en/stable/objects.inv
+            - https://www.attrs.org/en/stable/objects.inv
+            - https://multidict.readthedocs.io/en/stable/objects.inv
+            - https://yarl.readthedocs.io/en/stable/objects.inv
+          options:
+            filters: ["!^_"]
+            heading_level: 3
+            annotations_path: brief
+            docstring_section_style: spacy
+            docstring_style: numpy
+            inherited_members: false
+            merge_init_into_class: true
+            separate_signature: true
+            show_signature_annotations: true
+            show_source: false
+            allow_inspection: true
+            show_submodules: false
+            signature_crossrefs: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            find_stubs_package: true
+            extensions:
+                - griffe_inherited_docstrings

pyproject.toml

@@ -48,6 +48,9 @@ test = [
     "typing-extensions>=4.3,<5",
     "tzdata; sys_platform == 'win32'",
 ]
+docs = [
+    "mkdocs"
+]
 
 [tool.pyright]
 typeCheckingMode = "standard"

pyvolt/__init__.py

@@ -1,11 +1,9 @@
 """
-Revolt API Wrapper
-~~~~~~~~~~~~~~~~~~~
+# PyVolt
 
-A basic wrapper for the Revolt API.
+A sane Python framework for writing modern Revolt bots.
 
-:copyright: (c) 2024-present MCausc78
-:license: MIT, see LICENSE for more details.
+To get started, you will want to initialize an instance of [`pyvolt.client.Client`][].
 
 """
 

scripts/docs/gen_ref_pages.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2020 Nekokatt
+# Copyright (c) 2021-present davfsa
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Generate the code reference pages.
+
+Based on https://mkdocstrings.github.io/recipes/#generate-pages-on-the-fly
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(pathlib.Path("pyvolt").rglob("*.py")):
+    module_path = path.relative_to(".").with_suffix("")
+    doc_path = path.relative_to(".").with_suffix(".md")
+    full_doc_path = pathlib.Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    index = False
+
+    # Ignore the internals module
+    if "internal" in parts:
+        continue
+    elif parts[-1] == "__init__":
+        index = True
+        parts = parts[:-1]
+        # Make the __init__.py the index page of the module
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+
+    # Ignore dunder and private modules
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    # We could probably use some sort of template file for this if needed
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        full_name = ".".join(parts)
+        fd.write(
+            "---\n"
+            f"title: `{full_name}`\n"
+            f"description: {full_name} - API reference\n"
+            "---\n"
+            f"# `{full_name}`\n"
+            f"::: {full_name}\n"
+        )
+
+        # As of this commit b327b908 in griffe the idea of "exported" members has changed
+        # when it comes to `__init__` files, but we can work around it by explicitly
+        # removing all members from the init renders, leaving only the docstrings
+        # see: https://github.com/mkdocstrings/griffe/commit/b327b908d9546c8eb8f4ce5d3a216309937a6552
+        # see: https://github.com/mkdocstrings/python/issues/39
+        if index:
+            fd.write("    options:\n")
+            fd.write("      members: false\n")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, pathlib.Path("..", path))
+
+with mkdocs_gen_files.open("reference/summary.md", "w") as nav_file:
+    for item in nav.items():
+        path = pathlib.Path(item.filename).with_suffix("")
+
+        if path.name == "index":
+            path = path.parent
+
+        full_name = ".".join(path.parts)
+        nav_file.write("    " * item.level + f"* [{full_name}]({item.filename})\n")
+
+        print(f"- Created: {path.name}")