docs: Added more details to docs examples (#23)

Author: DenverCoder1

LICENSE

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2021 The Nextcord Developers
-Copyright (c) 2015-2020 Danny Y. (Rapptz)
+Copyright (c) 2020-2021 Danny Y. (Rapptz)
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),

README.md

@@ -35,4 +35,4 @@ py -3 -m pip install -U nextcord-ext-menus
 ## License
 
 Copyright (c) 2021 The Nextcord Developers  
-Copyright (c) 2015-2020 Danny Y. (Rapptz)
+Copyright (c) 2020-2021 Danny Y. (Rapptz)

docs/conf.py

@@ -4,7 +4,7 @@
 
 
 project = "nextcord-ext-menus"
-copyright = "2021-present, Nextcord. 2020-2021, Danny (Rapptz)"
+copyright = "2021 Nextcord. 2020-2021 Danny (Rapptz)"
 author = "Nextcord"
 
 sys.path.insert(0, os.path.abspath(".."))

docs/ext/menus/button_menus.rst

@@ -58,26 +58,45 @@ Instantiation is the same as for :ref:`Reaction Menus <ext_menus_reaction_menus>
 
 .. code:: py
 
-    await MyButtonMenu().start(ctx)
+    @bot.command()
+    async def menu_example(ctx):
+        await MyButtonMenu().start(ctx)
 
 .. _pagination-1:
 
 Pagination
 ~~~~~~~~~~
 
-A :class:`ButtonMenuPages` class is provided for pagination with button
-components.
+A :class:`ButtonMenuPages` class is provided for pagination with button components.
 
-:class:`ButtonMenuPages` works the same way as :class:`MenuPages`, but with :class:`Button <nextcord.ui.Button>` components instead of reactions.
+:class:`ButtonMenuPages` works the same way as :class:`MenuPages`, but with
+:class:`Button <nextcord.ui.Button>` components instead of reactions.
 
-A :class:`nextcord.ButtonStyle` can optionally be passed in to customize the
-appearance of the buttons.
+A :class:`nextcord.ButtonStyle` can optionally be passed in to customize the appearance of the buttons.
 
-``MySource`` is the same as :ref:`defined earlier <MySource>`, but the menu is instantiated
-with:
+The :class:`PageSource` deals with the data representation and formatting of the data we want to paginate.
+
+``MySource`` is the same as :ref:`defined earlier <MySource>`, but the menu is instantiated with
+:class:`ButtonMenuPages` as follows:
 
 .. code:: py
 
-    pages = menus.ButtonMenuPages(source=MySource(range(1, 100)), clear_buttons_after=True, 
-                                  style=nextcord.ButtonStyle.primary)
-    await pages.start(ctx)
+    from nextcord.ext import menus
+
+    class MySource(menus.ListPageSource):
+        def __init__(self, data):
+            super().__init__(data, per_page=4)
+
+        async def format_page(self, menu, entries):
+            offset = menu.current_page * self.per_page
+            return '\n'.join(f'{i}. {v}' for i, v in enumerate(entries, start=offset))
+
+    @bot.command()
+    async def pages_example(ctx):
+        data = ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"]
+        pages = menus.ButtonMenuPages(
+            source=MySource(data),
+            clear_buttons_after=True,
+            style=nextcord.ButtonStyle.primary,
+        )
+        await pages.start(ctx)

docs/ext/menus/menu_examples.rst

@@ -12,12 +12,23 @@ For pagination examples, see :ref:`ext_menus_pagination_examples`.
 
 .. contents::
 
+Reaction Menus
+--------------
+
 Basic Reaction Menu
--------------------
+~~~~~~~~~~~~~~~~~~~
+
+This example shows how to make a reaction menu with three buttons.
+
+All reaction menus are created by subclassing :class:`Menu`.
+
+Reactions are added to the menu using the :func:`button` decorator.
+
+To start the menu, call :meth:`start() <Menu.start>` on the menu, passing
+:class:`Context <nextcord.ext.commands.Context>`.
 
 .. code:: py
 
-    import nextcord
     from nextcord.ext import commands, menus
 
     bot = commands.Bot(command_prefix="$")
@@ -45,7 +56,11 @@ Basic Reaction Menu
     bot.run('token')
 
 Wait for Confirmation
----------------------
+~~~~~~~~~~~~~~~~~~~~~
+
+In this example, we make a reaction menu that waits for a confirmation from the user.
+
+We do this by using the ``wait=True`` argument to :meth:`start() <Menu.start>`.
 
 .. code:: py
 
@@ -78,8 +93,21 @@ Wait for Confirmation
         if confirm:
             await ctx.send('deleted...')
 
+Button Menus
+------------
+
 Basic Button Menu
------------------
+~~~~~~~~~~~~~~~~~
+
+This example shows how to make a button menu like the reaction version shown above.
+
+To use buttons instead of reactions, we will use :class:`ButtonMenu` instead of :class:`Menu`
+and :func:`nextcord.ui.button` instead of the :func:`menus.button() <button>` decorator.
+
+We also need to pass ``view=self`` in the initial message for the buttons to appear.
+
+To start the menu, call :meth:`start() <ButtonMenu.start>` on the menu, passing
+:class:`Context <nextcord.ext.commands.Context>`.
 
 .. code:: py
 
@@ -107,7 +135,12 @@ Basic Button Menu
         await MyButtonMenu().start(ctx)
 
 Button Confirm
---------------
+~~~~~~~~~~~~~~
+
+In this example, we make a button menu that waits for a confirmation from the user.
+
+We use the ``wait=True`` argument to :meth:`start() <ButtonMenu.start>` and create
+the :class:`ButtonMenu` in the same way as shown before.
 
 .. code:: py
 
@@ -135,6 +168,6 @@ Button Confirm
             return self.result
 
     @bot.command()
-    async def button_confirm(ctx: commands.Context):
+    async def button_confirm(ctx):
         confirm = await ButtonConfirm("Confirm?").prompt(ctx)
         await ctx.send(f"You said: {confirm}")