docs: add documentation (#25)

* docs: document init well

* docs: document errors

* docs: document filters

This might be the best docs I have done.

* docs: document route planner

* docs: document node

* docs: document player

* docs: document playlist

* docs: document plugin

* docs: document pool

* docs: document region

* docs: document search_type

* docs: document stats

* docs: document strategy

* docs: document track

* docs: document warnings

* docs: initial sphinx config

* docs: add documentation to rst files with sphinx

* docs: improve colours

* ci(lint): install docs deps

.flake8

@@ -0,0 +1,7 @@
+[flake8]
+max-line-length = 88
+per-file-ignores =
+    __init__.py: F401,F403
+# Black already handles E501 - line too long, ignored for docstring anomolies.
+# W503 - line break before binary operator, ignored for Black, flake8 cannot decide what style lmao.
+extend-ignore = E501,W503

.github/workflows/lint.yml

@@ -33,7 +33,7 @@ jobs:
         uses: snok/install-poetry@v1
 
       - name: Export dependencies
-        run: poetry export --no-interaction -f requirements.txt --output requirements.txt --with lint
+        run: poetry export --no-interaction -f requirements.txt --output requirements.txt --with lint,docs
 
       - name: Install dependencies
         run: pip install -r requirements.txt

.pre-commit-config.yaml

@@ -48,6 +48,7 @@ repos:
         name: Check for debug statements.
       - id: end-of-file-fixer
         name: Check for only one newline character at EOL.
+        exclude: "^(test_bot/logs/)"
       - id: trailing-whitespace
         name: Check for trailing whitespace.
         args: [--markdown-linebreak-ext=md]

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,111 @@
+/* attribute tables */
+/*noinspection ALL*/
+.py-attribute-table {
+  display: flex;
+  flex-wrap: wrap;
+  flex-direction: row;
+  margin: 0 2em;
+  padding-top: 16px;
+}
+
+.py-attribute-table-column {
+  flex: 1 1 auto;
+}
+
+.py-attribute-table-column > span {
+  font-weight: bold;
+  color: var(--color-foreground-primary);
+}
+
+main .py-attribute-table-column > ul {
+  list-style: none;
+  margin: 4px 0;
+  padding-left: 0;
+  font-size: 0.95em;
+}
+
+.py-attribute-table-entry {
+  margin: 0;
+  padding: 2px 0 2px 0.2em;
+  border-left: 2px solid var(--color-background-border);
+  display: flex;
+  line-height: 1.2em;
+}
+
+.py-attribute-table-entry > a {
+  padding-left: 0.5em;
+  color: var(--color-foreground-primary);
+  flex-grow: 1;
+}
+
+.py-attribute-table-entry > a:hover {
+  color: var(--color-brand-content);
+  text-decoration: none;
+}
+
+.py-attribute-table-entry:hover {
+  background-color: var(--color-background-hover);
+  border-left: 2px solid var(--color-brand-content);
+  text-decoration: none;
+}
+
+.py-attribute-table-badge {
+  flex-basis: 3em;
+  text-align: right;
+  font-size: 0.9em;
+  color: var(--color-foreground-secondary);
+  -moz-user-select: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+/* Defaults to... */
+.default-value-section {
+  margin-bottom: 6px;
+}
+.default-value-section .default-value-label {
+  font-style: italic;
+}
+.default-value-section code {
+  color: #306998;
+}
+
+/* ..container:: operations */
+.container.operations {
+  padding: 10px;
+  border: 1px solid var(--color-code-background);
+  margin-bottom: 20px;
+}
+
+.container.operations::before {
+  content: "Supported Operations";
+  color: var(--color-code-foreground);
+  display: block;
+  padding-bottom: 0.5em;
+}
+
+.container.operations > dl.describe > dt {
+  background-color: var(--color-api-background);
+}
+
+/* custom colours */
+body {
+  --color-brand-primary: hsl(220, 75%, 40%);
+  --color-brand-content: hsl(277, 75%, 40%);
+  --color-problematic: hsl(300, 75%, 33%);
+}
+
+@media not print {
+  @media (prefers-color-scheme: dark) {
+    body:not([data-theme="light"]) {
+      --color-brand-primary: hsl(210, 85%, 75%);
+      --color-brand-content: hsl(267, 85%, 75%);
+      --color-problematic: hsl(290, 85%, 75%);
+    }
+  }
+  body[data-theme="dark"] {
+    --color-brand-primary: hsl(210, 85%, 75%);
+    --color-brand-content: hsl(267, 85%, 75%);
+    --color-problematic: hsl(290, 85%, 75%);
+  }
+}

docs/api/errors-and-warnings.rst

@@ -0,0 +1,45 @@
+.. currentmodule:: mafic
+
+Errors and Warnings
+===================
+
+Errors
+------
+
+.. exception_hierarchy::
+
+   - :exc:`Exception`
+      - :exc:`MaficException`
+         - :exc:`LibraryCompatibilityError`
+            - :exc:`NoCompatibleLibraries`
+            - :exc:`MultipleCompatibleLibraries`
+         - :exc:`PlayerException`
+            - :exc:`TrackLoadException`
+            - :exc:`PlayerNotConnected`
+         - :exc:`NodeAlreadyConnected`
+         - :exc:`NoNodesAvailable`
+
+
+.. autoexception:: MaficException
+
+.. autoexception:: LibraryCompatibilityError
+
+.. autoexception:: NoCompatibleLibraries
+
+.. autoexception:: MultipleCompatibleLibraries
+
+.. autoexception:: PlayerException
+
+.. autoexception:: TrackLoadException
+   :exclude-members: from_data
+
+.. autoexception:: PlayerNotConnected
+
+.. autoexception:: NoNodesAvailable
+
+.. autoexception:: NodeAlreadyConnected
+
+Warnings
+--------
+
+.. autoclass:: UnsupportedVersionWarning

docs/api/filters.rst

@@ -0,0 +1,73 @@
+.. currentmodule:: mafic
+
+Filters
+=======
+
+A :class:`Filter` is used with :meth:`Player.add_filter` to modify the playback of a
+:class:`Track`.
+
+.. ChannelMix
+.. Distortion
+.. EQBand
+.. Filter
+.. Karaoke
+.. LowPass
+.. Rotation
+.. Timescale
+.. Tremolo
+.. Vibrato
+
+.. attributetable:: Filter
+
+.. autoclass:: Filter
+   :exclude-members: payload
+
+.. attributetable:: ChannelMix
+
+.. autoclass:: ChannelMix
+   :exclude-members: payload
+
+.. attributetable:: Distortion
+
+.. autoclass:: Distortion
+   :exclude-members: payload
+
+.. attributetable:: EQBand
+
+.. autoclass:: EQBand
+   :exclude-members: payload
+
+.. attributetable:: Equalizer
+
+.. autoclass:: Equalizer
+   :exclude-members: payload
+
+.. attributetable:: Karaoke
+
+.. autoclass:: Karaoke
+   :exclude-members: payload
+
+.. attributetable:: LowPass
+
+.. autoclass:: LowPass
+   :exclude-members: payload
+
+.. attributetable:: Rotation
+
+.. autoclass:: Rotation
+   :exclude-members: payload
+
+.. attributetable:: Timescale
+
+.. autoclass:: Timescale
+   :exclude-members: payload
+
+.. attributetable:: Tremolo
+
+.. autoclass:: Tremolo
+   :exclude-members: payload
+
+.. attributetable:: Vibrato
+
+.. autoclass:: Vibrato
+   :exclude-members: payload

docs/api/index.rst

@@ -0,0 +1,18 @@
+API Reference
+=============
+
+The full API reference for Mafic:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   node-management
+   node
+   stats
+   ip
+   player
+   track-and-playlist
+   filters
+   errors-and-warnings
+   utils

docs/api/ip.rst

@@ -0,0 +1,40 @@
+.. currentmodule:: mafic
+
+IP Block Management
+===================
+
+This file contains info obtained from :meth:`Node.fetch_route_planner_status`.
+
+.. autoclass:: IPRoutePlannerType
+
+.. autoclass:: IPBlockType
+
+.. attributetable:: IPBlock
+
+.. autoclass:: IPBlock
+
+.. attributetable:: FailingAddress
+
+.. autoclass:: FailingAddress
+
+.. attributetable:: BaseIPRoutePlannerStatus
+
+.. autoclass:: BaseIPRoutePlannerStatus
+
+.. attributetable:: BalancingIPRoutePlannerStatus
+
+.. autoclass:: BalancingIPRoutePlannerStatus
+
+.. attributetable:: NanoIPRoutePlannerStatus
+
+.. autoclass:: NanoIPRoutePlannerStatus
+
+.. attributetable:: RotatingIPRoutePlannerStatus
+
+.. autoclass:: RotatingIPRoutePlannerStatus
+
+.. attributetable:: RotatingNanoIPRoutePlannerStatus
+
+.. autoclass:: RotatingNanoIPRoutePlannerStatus
+
+.. autodata:: mafic.ip.RoutePlannerStatus

docs/api/node-management.rst

@@ -0,0 +1,27 @@
+.. currentmodule:: mafic
+
+Node Management
+===============
+
+This file is about managing nodes and selecting the best node for a player.
+
+.. autodata:: mafic.type_variables.ClientT
+
+.. attributetable:: NodePool
+
+.. autoclass:: NodePool
+
+.. autodata:: mafic.pool.StrategyList
+
+.. autodata:: mafic.strategy.StrategyCallable
+
+.. autoclass:: Strategy
+
+.. autoclass:: VoiceRegion
+   :undoc-members:
+
+.. autoclass:: Region
+   :undoc-members:
+
+.. autoclass:: Group
+   :undoc-members:

docs/api/node.rst

@@ -0,0 +1,11 @@
+.. currentmodule:: mafic
+
+Nodes
+=====
+
+A :class:`Node` is one lavalink instance.
+
+.. attributetable:: Node
+
+.. autoclass:: Node
+   :exclude-members: voice_update

docs/api/player.rst

@@ -0,0 +1,15 @@
+.. currentmodule:: mafic
+
+Player
+======
+
+A :class:`Player` is used to interact with a :class:`Node` via a voice client managed by
+your Discord library.
+
+.. attributetable:: Player
+
+.. autoclass:: Player
+   :exclude-members: on_voice_server_update, on_voice_state_update, update_state
+
+.. autoclass:: SearchType
+   :undoc-members: