even more review fixes

docs/source/tutorials.rst

@@ -16,8 +16,8 @@ programming. But let's not get ahead of ourselves; you are here for the basics!
     :titlesonly:
 
     tutorials/first-plugin
-    tutorials/playing-command
-    tutorials/configurable
+    tutorials/playing-with-commands
+    tutorials/configuration-and-setup
 
 
 Requirements
@@ -32,6 +32,6 @@ Before you can dive into these tutorials, you will need the following:
   to import a module, etc.)
 
 Since you'll be running Sopel, we invite you to create a configuration file
-that connects to a friendly IRC server and joins a private testing channel. That
-way, when you restart your bot, or run your command for the hundredth time, you
-won't spam other users.
+that connects to a friendly IRC server and joins a private testing channel.
+That way, when you restart your bot, or run your command for the hundredth
+time, you won't spam other users.

docs/source/tutorials/configurable.rst → docs/source/tutorials/configuration-and-setup.rst

@@ -29,15 +29,15 @@ Telling Sopel about it
 ======================
 
 Now, having a class in your plugin doesn't achieve much: you need to tell the
-bot about it. The best place to do so is in the :func:`setup` function
-hook of your plugin::
+bot about it by using the :meth:`~sopel.config.Config.define_section` method.
+The best place to do so is in the :func:`setup` function hook of your plugin::
 
     def setup(bot):
         bot.settings.define_section('myplugin', MyPluginSection)
 
-This way, you tell Sopel that the ``[myplugin]`` section is used by your
-plugin, and to parse this section Sopel must use your class, i.e.
-``MyPluginSection``.
+This way, you tell Sopel that the ``[myplugin]`` section in the **configuration
+file** is used by your plugin, and to parse this section Sopel must use your
+class, i.e. ``MyPluginSection``.
 
 
 Using your section
@@ -55,8 +55,8 @@ following lines in your configuration file:
         peach
         strawberry
 
-And Sopel will expose that for you through ``bot.settings``. For example, you
-can write this command::
+And Sopel will expose that for you through ``bot.settings.myplugin``. For
+example, you can write this command::
 
     import random
 
@@ -96,11 +96,15 @@ before (``~/.sopel/plugins/myplugin.py``, assuming the default location)::
         fruit = random.choice(bot.settings.myplugin.fruits)
         bot.say(f'I want a {fruit}!')
 
-As you can see, there are several steps when it comes to configuration. Sopel
-tries to make it as straightforward and flexible as possible for you to declare
-and to setup your plugin configuration, and it offers various possibilities.
+As you can see, there are **several steps** when it comes to configuration:
 
-You can read more about :ref:`plugin configuration <plugin-anatomy-config>`,
+* creating a class to represent your configuration section
+* telling Sopel about it in a ``setup`` function
+* using your plugin's configuration in your plugin
+
+Sopel tries to make it as straightforward and flexible as possible for you to
+declare and to setup your plugin configuration, and you can read more about
+:ref:`plugin configuration <plugin-anatomy-config>`,
 which includes a section about the configuration wizard as well. You can also
 see Sopel's own configuration in
 :doc:`the configuration chapter </configuration>`.

docs/source/tutorials/playing-command.rst → docs/source/tutorials/playing-with-commands.rst

@@ -1,6 +1,6 @@
-=========================
-Playing with your command
-=========================
+====================
+Playing with command
+====================
 
 Now that you have started :doc:`your first plugin <first-plugin>`, maybe you
 want to write a more interesting command than the basic ``.hello`` one. Not
@@ -24,8 +24,8 @@ arguments?** The first one is the ``bot``, an instance of Sopel that you can
 use to
 :doc:`interact with the bot </plugin/bot>`.
 
-In the previous tutorial, we used ``bot.reply``, which is convenient when             
-responding directly to a user, but not always what you want. Maybe you want the       
+In the previous tutorial, we used ``bot.reply``, which is convenient when
+responding directly to a user, but not always what you want. Maybe you want the
 bot to say something more complex::
 
     <YourNick> .hello