From 0f5e4982688c3b2fd13ab23a1b190148cfe3dc46 Mon Sep 17 00:00:00 2001
From: FasterSpeeding <lucina@lmbyrne.dev>
Date: Mon, 28 Aug 2023 04:07:51 +0100
Subject: [PATCH] Add the commands to the usage guide (#119)

Co-authored-by: always-on-duty[bot] <120557446+always-on-duty[bot]@users.noreply.github.com>
---
 docs/usage.md                | 50 ++++++++++++++++++++++++++++++++++++
 tanchan/components/config.py | 32 +++++++++++++++++++++++
 2 files changed, 82 insertions(+)

diff --git a/docs/usage.md b/docs/usage.md
index da716441..2eafea13 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -23,3 +23,53 @@ as the command's description.
 [tanchan.doc_parse.with_annotated_args][] uses the functionality exposed in [tanjun.annotations][]
 but with the added feature that slash command option descriptions are parsed from the docstring.
 This supports Google's doc style, NumPy's doc style, and Sphinx's "reST" doc style.
+
+### Commands
+
+Tan-chan provides several Tanjun commands which rely on the separate Yuyo
+components library. To ensure a compatible Yuyo version is present you
+should install Tan-chan with the `tanchan[yuyo]` install flag.
+
+`"tanchan.components"` can be passed to
+[Client.load_modules][tanjun.abc.Client.load_modules] as a shorthand to
+add all of these commands and component handlers to a bot at once.
+
+!!! note
+    Any command config should be added the Tanjun client before the commands
+    are loaded.
+
+##### Help command
+
+Tan-chan implements help commands which give users more information about
+the commands loaded in a bot.
+
+The message command this introduces can be called as either `{prefix}help` to
+get a list of all available commands or as `{prefix}help {command name}` to get
+more information about a specific command. Commands are grouped by the name of
+their linked component by default so it's important to make sure you're passing
+legible `name=`s to
+[tanjun.Component.\_\_init\_\_][tanjun.components.Component.__init__].
+
+By default slash command functionality is turned off but this can be enabled
+using [tanchan.components.config.HelpConfig][].
+
+These commands can be added to a bot by calling
+[Client.load_modules][tanjun.abc.Client.load_modules] with
+`"tanchan.components.help"`.
+
+##### Eval command
+
+Tan-chan implements eval commands which allow bot owners to dynamically
+evaluate code in the bot's runtime.
+
+The message command this introduces can be called simply by sending
+`{prefix}eval` followed by a markdown codeblock of the code to execute.
+
+The slash eval command isn't included by default but this can be set to be
+declared globally or for specific guilds using
+[tanchan.components.config.EvalConfig][] and its relevant `eval_guild_ids`
+option.
+
+These commands can be added to a bot by calling
+[Client.load_modules][tanjun.abc.Client.load_modules] with
+`"tanchan.components.eval"`.
diff --git a/tanchan/components/config.py b/tanchan/components/config.py
index 7cf894f1..dd525445 100644
--- a/tanchan/components/config.py
+++ b/tanchan/components/config.py
@@ -50,6 +50,16 @@ class EvalConfig:
 
     [EvalConfig.add_to_client][tanchan.components.config.EvalConfig.add_to_client]
     should be used to set this config.
+
+    Examples
+    --------
+    ```py
+    client = tanjun.Client.from_gateway_bot(bot)
+    (
+        yuyo.components.config.EvalConfig(eval_guild_ids=None)
+        .add_to_client(client)
+    )
+    ```
     """
 
     eval_guild_ids: typing.Optional[collections.Collection[int]] = attrs.field(default=())
@@ -76,6 +86,16 @@ class HelpConfig:
 
     [HelpConfig.add_to_client][tanchan.components.config.HelpConfig.add_to_client]
     should be used to set this config.
+
+    Examples
+    --------
+    ```py
+    client = tanjun.Client.from_gateway_bot(bot)
+    (
+        yuyo.components.config.HelpConfig(enable_slash_command=True)
+        .add_to_client(client)
+    )
+    ```
     """
 
     enable_message_command: bool = True
@@ -115,6 +135,18 @@ class Config(EvalConfig, HelpConfig):
 
     [Config.add_to_client][tanchan.components.config.Config.add_to_client]
     should be used to set this config.
+
+    Examples
+    --------
+    ```py
+    client = tanjun.Client.from_gateway_bot(bot)
+    config = yuyo.components.config.Config(
+        eval_guild_ids=None,
+        enable_slash_command=True,
+    )
+
+    config.add_to_client(client)
+    ```
     """
 
     def add_to_client(self, client: typing.Union[alluka.Client, tanjun.Client]) -> None: