Migrate documentation to mkdocs

.github/workflows/ci.yml

@@ -191,15 +191,13 @@ jobs:
       - name: Setup python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.9
-
-      - name: Setup node
-        uses: actions/setup-node@v4
+          # NOTE: This should be kept up to date with .readthedocs.yaml
+          python-version: 3.11
 
       - name: Build documentation
         run: |
           pip install -r dev-requirements.txt
-          nox -s sphinx
+          nox -s mkdocs
 
       - name: Upload artifacts
         if: github.event_name == 'pull_request'

.readthedocs.yaml

@@ -3,26 +3,14 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    # NOTE: This should be kept up to date with .ci.yml
+    python: "3.11"
 
-sphinx:
-  configuration: docs/conf.py
-  builder: dirhtml
+mkdocs:
+  configuration: mkdocs.yml
 
 python:
    install:
-     - requirements: dev-requirements/sphinx.txt
+     - requirements: dev-requirements/mkdocs.txt
      - method: pip
        path: .
-
-search:
-  ignore:
-    # Defaults
-    - search.html
-    - search/index.html
-    - 404.html
-    - 404/index.html
-
-    # Custom
-    - index.html
-    - changelog/index.html

README.md

@@ -22,7 +22,7 @@ Python 3.8, 3.9, 3.10, 3.11 and 3.12 are currently supported.
 
 ## Installation
 
-Install Hikari from PyPI with the following command:
+Install hikari from PyPI with the following command:
 
 ```bash
 python -m pip install -U hikari
@@ -35,6 +35,7 @@ py -3 -m pip install -U hikari
 ## Bots
 
 Hikari provides two different default bot implementations to suit your needs:
+
 - [GatewayBot](#gatewaybot)
 - [RESTBot](#restbot)
 
@@ -194,6 +195,7 @@ bot.run(
 
 Many other helpful options exist for you to take advantage of if you wish. Links to the respective docs can be seen
 below:
+
 - [GatewayBot.run](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/gateway_bot/#hikari.impl.gateway_bot.GatewayBot.run)
 - [RESTBot.run](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/rest_bot/#hikari.impl.rest_bot.RESTBot.run)
 
@@ -246,14 +248,20 @@ python -m pip install -U hikari[speedups, server]
 
 ## Additional resources
 
-You may wish to use a command framework on top of Hikari so that you can start writing a bot quickly without
+You may wish to use a command framework on top of hikari so that you can start writing a bot quickly without
 implementing your own command handler.
 
 Hikari does not include a command framework by default, so you will want to pick a third party library to do it:
 
-- [`lightbulb`](https://github.com/tandemdude/hikari-lightbulb) - a simple and easy to use command framework for Hikari.
-- [`tanjun`](https://github.com/FasterSpeeding/Tanjun) - a flexible command framework designed to extend Hikari.
-- [`crescent`](https://github.com/magpie-dev/hikari-crescent) - a command handler for Hikari that keeps your project neat and tidy.
+- [`arc`](https://github.com/hypergonial/hikari-arc) - a bot framework with a focus on type-safety and correctness.
+- [`crescent`](https://github.com/magpie-dev/hikari-crescent) - a command handler for hikari that keeps your project neat and tidy.
+- [`lightbulb`](https://github.com/tandemdude/hikari-lightbulb) - a simple and easy to use command framework for hikari.
+- [`tanjun`](https://github.com/FasterSpeeding/Tanjun) - a flexible command framework designed to extend hikari.
+
+There are also third party libraries to help you manage components:
+
+- [`miru`](https://github.com/hypergonial/hikari-miru) - A component handler for hikari, inspired by discord.py's views.
+- [`flare`](https://github.com/brazier-dev/hikari-flare/) - a component manager designed to write simple interactions with persistent data.
 
 ---
 
@@ -307,7 +315,7 @@ Currently, this functionality does not yet exist.
 
 ---
 
-## Developing Hikari
+## Developing hikari
 
 To familiarize yourself a bit with the project, we recommend reading our
 [contributing manual](https://github.com/hikari-py/hikari/blob/master/CONTRIBUTING.md).

changes/1810.documentation.md

@@ -0,0 +1 @@
+Switch documentation to mkdocs

dev-requirements/mkdocs.txt

@@ -0,0 +1,18 @@
+mkdocs==1.5.3
+
+# Mkdocs Material
+mkdocs-material[imaging]==9.5.14
+
+# Docstring parsing for API reference
+mkdocstrings[python]==0.24.1
+griffe-inherited-docstrings==1.0.0
+
+# Generate API reference pages dynamically
+mkdocs-gen-files==0.5.0
+mkdocs-literate-nav==0.6.1
+
+# Formatting signatures
+black==24.3.0
+
+# Image viewer ext
+mkdocs-glightbox==0.3.7

docs/changelog.md

@@ -0,0 +1,12 @@
+---
+title: Changelog
+description: Learn what the latest changes are!
+hide:
+  - navigation
+---
+
+!!! warning
+    Major and minor releases also include the changes specified in prior development releases.
+
+
+--8<-- "CHANGELOG.md"