doc: Add actual documentation

Author: Skelmis

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+formats:
+  - pdf
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: "3.8"
+  install:
+    - requirements: docs/requirements.txt

cooldowns/buckets/hashable_arguments.py

@@ -2,6 +2,8 @@
 
 
 class _HashableArguments:
+    """An implementation class, you don't need to create these yourself."""
+
     # An internal class defined such that we can
     # use *args and **kwargs as keys. We need to
     # do this as mutable items are not hashable,

cooldowns/buckets/main.py

@@ -7,17 +7,19 @@ class CooldownBucket(Enum):
     """
     A collection of generic CooldownBucket's for usage in cooldown's.
 
+    See :py:class:`cooldowns.protocols.bucket.CooldownBucketProtocol`
+
     Attributes
     ==========
     all
         The buckets are defined using all
-        arguments passed to the :type:`Callable`
+        arguments passed to the `Callable`
     args
         The buckets are defined using all
-        non-keyword arguments passed to the :type:`Callable`
+        non-keyword arguments passed to the `Callable`
     kwargs
         The buckets are defined using all
-        keyword arguments passed to the :type:`Callable`
+        keyword arguments passed to the `Callable`
     """
 
     all = 0

cooldowns/cooldown.py

@@ -102,6 +102,8 @@ def shared_cooldown(
     """
     Wrap this Callable in a shared cooldown.
 
+    Use :py:meth:`define_shared_cooldown` before this.
+
     Parameters
     ----------
     cooldown_id: Optional[Union[int, str]]
@@ -299,7 +301,7 @@ def clear(
 
         Notes
         -----
-        You can get :class:`_HashableArguments` by
+        You can get :py:class:`_HashableArguments` by
         using the :meth:`Cooldown.get_bucket` method.
         """
         if not bucket:
@@ -350,8 +352,10 @@ def __repr__(self) -> str:
 
     @property
     def bucket(self) -> CooldownBucketProtocol:
+        """Returns the underlying bucket to process cooldowns against."""
         return self._bucket
 
     @property
     def func(self) -> Optional[Callable]:
+        """Returns the wrapped function."""
         return self._func

cooldowns/cooldown_times_per.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import datetime
-from asyncio import get_event_loop, AbstractEventLoop, Queue, QueueEmpty
+from asyncio import get_event_loop, AbstractEventLoop, Queue
 from typing import TYPE_CHECKING, Optional
 
 from cooldowns.exceptions import CallableOnCooldown

cooldowns/exceptions.py

@@ -34,7 +34,7 @@ class UnknownBucket(BaseCooldownException):
 
 class NoRegisteredCooldowns(BaseCooldownException):
     """
-    This :type:`Callable` has no attached cooldown's.
+    This `Callable` has no attached cooldown's.
     """
 
     def __init__(self):
@@ -43,16 +43,14 @@ def __init__(self):
 
 class CallableOnCooldown(BaseCooldownException):
     """
-    This :type:`Callable` is currently on cooldown.
+    This `Callable` is currently on cooldown.
 
     Attributes
     ==========
     func: Callable
-        The :type:`Callable` which is currently rate-limited
+        The `Callable` which is currently rate-limited
     cooldown: Cooldown
         The :class:`Cooldown` which applies to the current cooldown
-    retry_after: float
-        How many seconds before you can retry the :type:`Callable`
     resets_at: datetime.datetime
         The exact datetime this cooldown resets.
     """
@@ -73,6 +71,7 @@ def __init__(
 
     @property
     def retry_after(self) -> float:
+        """How many seconds before you can retry the `Callable`"""
         now = datetime.datetime.utcnow()
         gap: datetime.timedelta = self.resets_at - now
         return gap.seconds

cooldowns/utils.py

@@ -37,14 +37,14 @@ def _get_cooldowns_or_raise(func: MaybeCoro) -> List[Cooldown]:
 
 def get_remaining_calls(func: MaybeCoro, *args, **kwargs) -> int:
     """
-    Given a :type:`Callable`, return the amount of remaining
+    Given a `Callable`, return the amount of remaining
     available calls before these arguments will result
     in the callable being rate-limited.
 
     Parameters
     ----------
     func: MaybeCoro
-        The :type:`Callable` you want to check.
+        The `Callable` you want to check.
     args
         Any arguments you will pass.
     kwargs
@@ -53,13 +53,13 @@ def get_remaining_calls(func: MaybeCoro, *args, **kwargs) -> int:
     Returns
     -------
     int
-        How many more times this :type:`Callable`
+        How many more times this `Callable`
         can be called without being rate-limited.
 
     Raises
     ------
     NoRegisteredCooldowns
-        The given :type:`Callable` has no cooldowns.
+        The given `Callable` has no cooldowns.
 
     Notes
     -----
@@ -76,7 +76,7 @@ def get_remaining_calls(func: MaybeCoro, *args, **kwargs) -> int:
 
 def reset_cooldowns(func: MaybeCoro):
     """
-    Reset all cooldown's on this :type:`Callable`
+    Reset all cooldown's on this `Callable`
     back to default settings.
 
 

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/_build/doctrees/environment.pickle

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 65edb04b8da2860e356a1350783d6b93
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/doctrees/index.doctree

@@ -0,0 +1,34 @@
+Welcome to Function Cooldowns's documentation!
+==============================================
+
+Cooldowns for Coroutines, simple as that.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Main:
+
+
+   modules/decorators.rst
+   modules/util.rst
+   modules/buckets.rst
+   modules/exceptions.rst
+   modules/nextcord_slash_cooldowns.rst
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Object references:
+
+
+   modules/objects/util.rst
+   modules/objects/cooldown.rst
+   modules/objects/protocols.rst
+   modules/objects/hashable_args.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/_build/doctrees/modules/buckets.doctree

@@ -0,0 +1,21 @@
+Buckets
+=======
+
+The current bucket offerings which are built in.
+
+Note, this package is not dependant on Nextcord and
+if you do not have it there won't be any issues if you don't use it.
+
+.. currentmodule:: cooldowns.buckets
+
+.. autoclass:: CooldownBucket
+    :members:
+    :noindex:
+
+This requires a full import, and Nextcord.
+
+.. currentmodule:: cooldowns.buckets.slash
+
+.. autoclass:: SlashBucket
+    :members:
+    :noindex:

docs/_build/doctrees/modules/decorators.doctree

@@ -0,0 +1,13 @@
+Decorator Usage
+===============
+
+You have two choices for decorators, as documented below.
+
+For example usages, view the examples section.
+
+
+.. currentmodule:: cooldowns
+
+.. autofunction:: cooldown
+
+.. autofunction:: shared_cooldown

docs/_build/doctrees/modules/exceptions.doctree

@@ -0,0 +1,35 @@
+Library Exceptions
+==================
+
+All exceptions inherit from ``BaseCooldownException``
+
+.. currentmodule:: cooldowns.exceptions
+
+.. autoclass:: BaseCooldownException
+    :members:
+    :undoc-members:
+
+.. autoclass:: NonExistent
+    :members:
+    :undoc-members:
+
+
+.. autoclass:: CooldownAlreadyExists
+    :members:
+    :undoc-members:
+
+
+.. autoclass:: UnknownBucket
+    :members:
+    :undoc-members:
+
+
+.. autoclass:: NoRegisteredCooldowns
+    :members:
+    :undoc-members:
+
+
+.. autoclass:: CallableOnCooldown
+    :members:
+    :undoc-members:
+