Begin writing lightbulb-by-example pages. Migrate current docs to usi…

…ng MyST instead of rST
tandemdude · Aug 8, 2024 · 71a8f89 · 71a8f89
1 parent 8386f9d
commit 71a8f89
Show file tree

Hide file tree

Showing 30 changed files with 967 additions and 1,057 deletions.
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/by-example.md b/docs/source/by-example.md
@@ -0,0 +1,102 @@
+(by-example)=
+# Lightbulb By Example
+
+::::{grid} 1 2 2 2
+:gutter: 3
+
+:::{grid-item-card} {material-outlined}`flag;2em` Preface
+:columns: 12
+:link: 0-preface
+:link-type: ref
+
+Introduction to Lightbulb - including project setup and first steps.
+:::
+
+:::{grid-item-card} {material-outlined}`keyboard_command_key;2em` Commands
+:link: 1-commands
+:link-type: ref
+
+What is a command and how to create them.
+:::
+
+:::{grid-item-card} {material-outlined}`settings;2em` Options
+:link: 2-options
+:link-type: ref
+
+Taking user input for commands and how to use it.
+:::
+
+:::{grid-item-card} {material-outlined}`menu_open;2em` Context Menus
+:link: 3-context-menus
+:link-type: ref
+
+What are context menu commands - how and why to use them.
+:::
+
+:::{grid-item-card} {material-outlined}`groups;2em` Groups
+:link: 4-groups
+:link-type: ref
+
+Why use a command group, and potential pitfalls using them.
+:::
+
+:::{grid-item-card} {material-outlined}`link;2em` Dependencies
+:link: 5-dependencies
+:link-type: ref
+
+What is dependency injection - accessing objects wherever you need them without global state.
+:::
+
+:::{grid-item-card} {material-outlined}`phishing;2em` Hooks
+:link: 6-hooks
+:link-type: ref
+
+Modifying command behaviour and conditionally blocking execution.
+:::
+
+:::{grid-item-card} {material-outlined}`power;2em` Extensions
+:link: 7-extensions
+:link-type: ref
+
+Splitting your application into multiple files - how extensions enable this.
+:::
+
+:::{grid-item-card} {material-outlined}`keyboard_alt;2em` Autocomplete
+:link: 8-autocomplete
+:link-type: ref
+
+Dynamically suggesting option values to your users.
+:::
+
+:::{grid-item-card} {material-outlined}`translate;2em` Localization
+:link: 9-localization
+:link-type: ref
+
+Catering to the international audience - how to translate command names and more.
+:::
+
+:::{grid-item-card} {material-outlined}`menu_book;2em` Appendix
+:columns: 12
+:link: 10-appendix
+:link-type: ref
+
+Further reading; more advanced concepts and techniques.
+:::
+::::
+
+:::{toctree}
+:hidden:
+:maxdepth: 2
+
+by-examples/000_preface
+by-examples/010_commands
+by-examples/020_options
+by-examples/030_context_menus
+by-examples/040_groups
+by-examples/050_dependencies
+by-examples/060_hooks
+by-examples/070_extensions
+by-examples/080_autocomplete
+by-examples/090_localization
+by-examples/100_appendix
+:::
diff --git a/docs/source/by-example.rst b/docs/source/by-example.rst
diff --git a/docs/source/by-examples/000_preface.md b/docs/source/by-examples/000_preface.md
@@ -1,3 +1,4 @@
+(0-preface)=
 # 0 - Preface
 
 Whether you are a new developer using Lightbulb, or a returning developer experienced using V2 you are likely to
@@ -21,13 +22,13 @@ For additional help with migrating existing code you should view the migration g
 1-to-1 replacements for common patterns that you have used before (although some functionality *may* have to be
 implemented yourself).
 
-```{note}
+:::{note}
 As of version 3, prefix command support has been completely removed. If you still wish to support prefix commands
 you will have to create a listener for Hikari's `MessageCreateEvent` and process and parse the messages manually.
 
 This may be more inconvenient for you but it allowed me to greatly simplify the internals and developer-facing
 API for a better experience (no more long decorator stacks).
-```
+:::
 
 ---
 
@@ -50,23 +51,46 @@ To get Lightbulb working in your project, you first need to create a Hikari bot
 [`hikari.GatewayBot`](https://docs.hikari-py.dev/en/latest/#gatewaybot) and [`hikari.RESTBot`](https://docs.hikari-py.dev/en/latest/#gatewaybot).
 The steps for setting up both to work with Lightbulb are the same:
 
+:::{tab} GatewayBot
 ```python
 import hikari
 import lightbulb
 
-bot = hikari.GatewayBot("your bot token")  # or hikari.RESTBot(...)
+bot = hikari.GatewayBot(
+    token="...",
+)
 # Set up the lightbulb client
 client = lightbulb.client_from_app(bot)
 ```
+:::
 
-The lightbulb client has to be started in order to sync commands with discord and begin processing interactions:
+:::{tab} RESTBot
+```python
+import hikari
+import lightbulb
 
+bot = hikari.RESTBot(
+    token="...",
+    token_type="...",
+    public_key="...",
+)
+# Set up the lightbulb client
+client = lightbulb.client_from_app(bot)
+```
+:::
+
+The Lightbulb client must then be started in order to sync commands with discord and begin processing interactions:
+
+:::{tab} GatewayBot
 ```python
-# if using hikari.GatewayBot
 bot.subscribe(hikari.StartingEvent, client.start)
+```
+:::
 
-# if using hikari.RESTBot
+:::{tab} RESTBot
+```python
 bot.add_startup_callback(client.start)
 ```
+:::
 
 You are now ready to write your first command.
diff --git a/docs/source/by-examples/010_commands.md b/docs/source/by-examples/010_commands.md
@@ -1,3 +1,4 @@
+(1-commands)=
 # 1 - Commands
 
 While 'Commands' in Lightbulb refer to Discord's [application commands](https://discord.com/developers/docs/interactions/overview#commands), in this section we will mainly be going over _slash_ commands. Context menu commands - user and message - will be explained later.
@@ -30,10 +31,10 @@ class YourCommand(
     ...
 ```
 
-```{note}
+:::{note}
 There are many other parameters that can be given when declaring commands. These are clarified in the documentation
 for the different command bases mentioned above.
-```
+:::
 
 The last thing that is required in your command declaration is an invocation method. This is a method that will be
 called when the command is invoked, and is the portion of your command declaration that contains the actual command
@@ -65,13 +66,15 @@ in Discord, you will see that nothing shows up in the command menu. In order to
 client that the command exists. For now, we will register the command directly to the Lightbulb client, but later on
 you will be introduced to loaders, which can allow some more flexibility in how you set up your bot.
 
-Similar to how we defined the invocation method, we use the `Client.register` decorator to tell the Lightbulb client
-about our command.
+Similar to how we defined the invocation method, we use the `Client.register` method to tell the Lightbulb client
+about our command. This method can either be used as a decorator, or as a regular method by passing the command
+as an argument
 
 Here's how that should look:
 
+:::{tab} Decorator
 ```python
-@client.register
+@client.register  # <---
 class HelloWorld(
     lightbulb.SlashCommand,
     name="hello-world",
@@ -81,9 +84,9 @@ class HelloWorld(
     async def invoke(self, ctx: lightbulb.Context) -> None:
         await ctx.respond("Hello World!")
 ```
+:::
 
-Or, you can also register the command in non-decorated form, like this:
-
+:::{tab} Method
 ```python
 class HelloWorld(
     lightbulb.SlashCommand,
@@ -94,15 +97,16 @@ class HelloWorld(
     async def invoke(self, ctx: lightbulb.Context) -> None:
         await ctx.respond("Hello World!")
 
-client.register(HelloWorld)
+client.register(HelloWorld)  # <---
 ```
+:::
 
-```{note}
+:::{note}
 You can also specify specific guilds that the command should be created in by passing the `guilds` argument, like so:
 `@client.register(guilds=[1234, 5678])`
 
 See the documentation on the method for more details.
-```
+:::
 
 After registering the command and re-running the bot, the command should now show up in Discord, and the bot should
 respond once you execute it!
diff --git a/docs/source/by-examples/020_options.md b/docs/source/by-examples/020_options.md
@@ -1,3 +1,4 @@
+(2-options)=
 # 2 - Options
 
 Now that you've managed to make a basic command and have your bot respond to the users, it would probably be useful to

diff --git a/docs/source/by-examples/030_context_menus.md b/docs/source/by-examples/030_context_menus.md
@@ -1,3 +1,4 @@
+(3-context-menus)=
 # 3 - Context Menus
 
 ~~ info about what a context menu command is ~~

diff --git a/docs/source/by-examples/040_groups.md b/docs/source/by-examples/040_groups.md
@@ -1 +1,2 @@
+(4-groups)=
 # 4 - Groups
diff --git a/docs/source/by-examples/050_dependencies.md b/docs/source/by-examples/050_dependencies.md
@@ -1,3 +1,4 @@
+(5-dependencies)=
 # 5 - Dependencies
 
 Now that your bot is coming along nicely, you are likely thinking about adding some features that may require
@@ -24,22 +25,23 @@ import aiohttp
 client.di.register_dependency(aiohttp.ClientSession, lambda: aiohttp.ClientSession())
 ```
 
-```{tip}
+::::{tip}
 Lightbulb registers some dependencies for you automatically depending on what type of application you pass when creating
 the client. You can see these below.
 
-When using `hikari.GatewayBot`:
+:::{tab} Always
+- `lightbulb.Client`
+- `hikari.api.RESTClient`
+:::
+:::{tab} GatewayBot
 - `hikari.GatewayBot`
 - `hikari.api.EventManager`
-
-When using `hikari.RESTBot`:
+:::
+:::{tab} RESTBot
 - `hikari.RESTBot`
 - `hikari.api.InteractionServer`
-
-Always:
-- `lightbulb.Client`
-- `hikari.api.RESTClient`
-```
+:::
+::::
 
 ## Injection
 
@@ -65,12 +67,12 @@ These are listed below:
 If you need to enable dependency injection on other functions, you can decorate it with `@lightbulb.with_di` - from
 then on, each time the function is called, lightbulb will attempt to dependency inject suitable parameters.
 
-```{note}
+:::{note}
 For a parameter to be suitable for dependency injection, it needs to match the following rules:
 - It **must** have a type annotation
 - It has no default value, or a default value of exactly `lightbulb.INJECTED`
 - It **cannot** be positional-only (injected parameters are always passed using keywords)
-```
+:::
 
 Simple example using the `aiohttp.ClientSession` registered before:
 
@@ -145,11 +147,11 @@ Listeners by themselves are not dependency injected, so you may need to use the
 `Client.di.get_dependency` method to retrieve the created dependencies instead. Refer to the previous section
 to see an example on how dependency cleanup could be implemented.
 
-```{note}
+:::{note}
 The `Client.di.get_dependency` method **does not** require a dependency injection context to
 be present due to it fetching the dependencies directly from the client, so it can be called
 whenever the client is available.
-```
+:::
 
 ## Disabling Dependency Injection
 

diff --git a/docs/source/by-examples/060_hooks.md b/docs/source/by-examples/060_hooks.md
@@ -1 +1,2 @@
+(6-hooks)=
 # 6 - Hooks
diff --git a/docs/source/by-examples/070_extensions.md b/docs/source/by-examples/070_extensions.md
@@ -1 +1,2 @@
+(7-extensions)=
 # 7 - Extensions
diff --git a/docs/source/by-examples/080_autocomplete.md b/docs/source/by-examples/080_autocomplete.md
@@ -1 +1,2 @@
+(8-autocomplete)=
 # 8 - Autocomplete
diff --git a/docs/source/by-examples/090_localization.md b/docs/source/by-examples/090_localization.md
@@ -1 +1,2 @@
+(9-localization)=
 # 9 - Localization
diff --git a/docs/source/by-examples/100_appendix.md b/docs/source/by-examples/100_appendix.md
@@ -1 +1,2 @@
+(10-appendix)=
 # 10 - Appendix