plugin_tutorial: further simplifications

- Remove the discussion of README and copyright header. These are already very self documenting
- Add links to the `help` syntax reference in use/getting_started
- Update the headings to include the contents of each file in addition to its name for easier navigation
- Further remove redundant language

develop/plugin_tutorial.rst

@@ -9,14 +9,12 @@ Introduction
 
 This page is a top-down guide on how to write new plugins for Limnoria.
 
-Before you start, you should be more-or-less familiar with how to use and
+Before you start, you should install a copy of Limnoria on the machine you
-manage a Limnoria instance (loading plugins, configuring options, etc.).
+intend to develop plugins on, as it includes some additional scripts like
-You should also install a copy of Limnoria on the machine you intend to develop
-plugins on, as it includes some additional scripts like
 :command:`supybot-plugin-create` to generate the plugin skeleton.
 
-We'll go through this tutorial by actually writing a new plugin, named Random
+We'll go through this tutorial by writing a new plugin, named Random with a
-with just a few commands.
+few commands.
 
 Generating the Plugin template
 ==============================
@@ -50,35 +48,19 @@ Here's an example session::
     commands relating to random numbers, including random sampling from a list
     and a simple dice roller.
 
-README.md
+.. _init-py:
-==========
+Plugin metadata (__init__.py)
+=============================
+The first file we'll look at is :file:`__init__.py`. This is the "glue" that
+makes a directory a Python package, and sets up how the plugin is actually
+loaded.
 
-This is the README page people will see when they download your plugin or view
+For Limnoria plugins specifically, there are some metadata fields you may wish
-it from a source control website. It's helpful to include a brief summary of
+to fill in:
-what the plugin does here, as well as list any third-party dependencies.
 
-The :command:`supybot-plugin-create` wizard should have already filled in the
+* ``__version__``: the plugin version (optional)
-README with the summary you provided.
+* ``__author__`` describes the author of the plugin, in the form of a
-
+  :class:`supybot.Author` instance::
-__init__.py
-===========
-The next file we'll look at is :file:`__init__.py`. If you're not so familiar
-with the Python import mechanism, think of it as sort of the "glue" file that
-pulls all the files in the plugin directory together when you load it.
-There are also a few administrative items here that can be queried from the bot,
-such as the plugin's author and contact info.
-
-At the top of the file you'll see the copyright header, with your name added as
-prompted in :command:`supybot-plugin-create`. Feel free to use whatever
-license you choose: the default is the bot's 3-clause BSD. For our example,
-we'll leave it as is.
-
-Here is a list of attributes you should usually look at:
-
-* ``__version__``: the plugin version. We'll make ours `"0.1"`
-* ``__author__`` should be an instance of the :class:`supybot.Author` class.
-  This optionally includes a full name, a short name (usually IRC nick), and
-  an e-mail address::
 
     __author__ = supybot.Author(name='Daniel DiPaolo', nick='Strike',
                                 email='somewhere@someplace.xxx')
@@ -86,14 +68,15 @@ Here is a list of attributes you should usually look at:
 * ``__contributors__`` is a dictionary mapping :class:`supybot.Author`
   instances to lists of things they contributed. See e.g. `in the Plugin plugin
   <https://github.com/progval/Limnoria/blob/master/plugins/Plugin/__init__.py#L42-L49>`_.
-  For now we have no contributors, so we'll leave it blank.
+  This is most useful if a plugin has had multiple authors / contributors in
+  its history.
 
 * ``__url__`` references the download URL for the plugin. Since this is just an
   example, we'll leave this blank.
 
-The rest of :file:`__init__.py` shouldn't be touched unless you are
+The rest of :file:`__init__.py` can be left alone unless you are using
-using third-party modules in your plugin. If you are, then you need to add
+third-party modules in your plugin. If you are, you may wish to add
-additional import statements and ``reload`` calls to all those modules, so that
+additional import statements and ``reload`` calls to those modules, so that
 they get reloaded with the rest of the plugin::
 
     from . import config
@@ -104,12 +87,18 @@ they get reloaded with the rest of the plugin::
     # to be reloaded when this plugin is reloaded.  Don't forget to
     # import them as well!
 
-config.py
+.. note::
-=========
+  If your plugin has any third-party dependencies, you may want to list them in
-:file:`config.py` is, unsurprisingly, where all the configuration stuff
+  the README and add a `requirements.txt <https://pip.pypa.io/en/stable/reference/requirements-file-format/>`_
-related to your plugin goes. For this tutorial, the Random plugin is simple
+  file for easy installation (via ``pip install -r requirements.txt``).
-enough that it doesn't need any config variables, so this file can be left as
+
-is.
+.. _config-py:
+Configuration (config.py)
+=========================
+:file:`config.py` defines the configuration variables for a plugin.
+For this tutorial, the Random plugin is simple enough that it doesn't
+have any config variables, so the template can be left as is. Writing plugin
+configuration is explained in depth in the :ref:`Plugin Config Tutorial <configuration-tutorial>`.
 
 To briefly outline this file's structure: the ``configure`` function is used by
 the :command:`supybot-wizard` wizard and allows users to configure the plugin
@@ -118,21 +107,19 @@ this is seldomly used by third-party plugins as they're generally installed
 *after* configuring the bot.)
 
 The following line registers an entry for the plugin in Limnoria's config
-registry, followed by any configuration groups and variable definitions::
+registry, followed by an example of how to register a config variable::
 
     Random = conf.registerPlugin('Random')
     # This is where your configuration variables (if any) should go.  For example:
     # conf.registerGlobalValue(Random, 'someConfigVariableName',
     #     registry.Boolean(False, _("""Help for someConfigVariableName.""")))
 
-Writing plugin configuration is explained in depth
+.. _plugin-py:
-in the :ref:`Advanced Plugin Config Tutorial <configuration-tutorial>`.
+Plugin commands (plugin.py)
-
+===========================
-plugin.py
+``plugin.py`` includes the core functionality of the plugin. For most plugins this will
-=========
+include command handlers, as well as anything else relevant to its
-``plugin.py`` includes the core code for the plugin. For most plugins this will
+purpose (database queries,
-include command handlers, as well as anything else that's relevant to its
-particular use case (database queries,
 :ref:`HTTP server endpoints <http_plugins>`,
 :ref:`IRC command triggers <do-method-handlers>`, etc.)
 
@@ -145,9 +132,8 @@ template::
 The bulk of the plugin definition then resides in a subclass of
 :class:`callbacks.Plugin`. By convention, the class name is equal to the name of
 the plugin, though this is not strictly required (the actual linkage is done by
-the ``Class = Random`` statement at the end of the file). It is helpful to fill
+the ``Class = Random`` statement at the end of the file). Note that the docstring
-in the plugin docstring with some more details on how to actually use the plugin
+of a plugin class also can be shown using the
-too: this info can be shown on a live bot using the
 ``plugin help <plugin name>`` command. ::
 
     class Random(callbacks.Plugin):
@@ -161,7 +147,7 @@ too: this info can be shown on a live bot using the
 
 For this sample plugin, we define a custom constructor (``__init__``) that
 instantiates a random number generator instance and pre-seeds it. This isn't
-technically necessary for Python's ``random`` module, but it helps outline
+technically necessary when using Python's ``random`` module, but it helps outline
 how to write a similar constructor. Notice in particular how you must pass in
 an ``irc`` argument in addition to ``self``.
 
@@ -195,8 +181,8 @@ Our first command definition can immediately follow:
 .. note::
     All functions used as commands must have an all lowercase name.
 
-A command function taking in no arguments from IRC will still require 4
+A command function taking in no arguments from IRC requires 4 arguments at base;
-arguments; they are as follows:
+they are as follows:
 
 - ``self``: refers to the class instance. It is common to keep local state
   for the plugin as instance variables within the plugin class.
@@ -208,29 +194,31 @@ arguments; they are as follows:
   use :ref:`@wrap <using-wrap>` for automatic argument type conversion should
   never need to interact with ``args`` directly.
 
-The function docstring is expected to be in a particular format. First, the very
+The function docstring is shown in the ``help`` command, and is expected to be
-first line dictates the argument list to be displayed when someone calls the
+in a specific format:
-``help`` command on this command (i.e., ``help random``). Then, leave a blank
+
-line and start the actual help string for the function. Don't worry about the
+- The first line shows the :ref:`argument list <help-syntax>` when someone calls the
-fact that it's tabbed in or anything like that, as the help command normalizes
+  ``help`` command on this command (i.e., ``help random``).
-it to make it look nice. This part should be fairly brief but sufficient to
+- The second line is blank.
-explain the function and what (if any) arguments it requires. Remember that this
+- Everything afterwards is the actual description of the command. This should be
-should fit in one IRC message which is typically around a 450 character limit.
+  brief enough to ideally fit in one IRC message, which is around a 450 character limit.
+  Indentation and line breaks are normalized by the ``help`` command, so it is fine
+  to wrap longer text onto multiple lines.
 
 The :py:meth:`irc.reply <supybot.callbacks.ReplyIrcProxy.reply>` call
 is a bit of magic: it issues a reply the same place as the message that
 triggered the command. i.e. this may be in a channel or in a private
 conversation with the bot.
 
-Lastly, notice that commands go through the :ref:`@wrap <using-wrap>`
+Lastly, command functions are registered with the bot using the :ref:`@wrap <using-wrap>`
-decorator for automatic argument type conversion. For commands that require no
+decorator. For commands that require no parameters, calling ``@wrap`` with no
-parameters, calling ``@wrap`` with no arguments is enough.
+arguments is sufficient.
 
 Command handler with parameters
 -------------------------------
 
-Now let's create a command with some arguments and see how we use those in our
+Now let's create a command with an argument.
-plugin commands. This ``seed`` command lets the user pick a specific RNG seed:
+The ``seed`` command lets the user pick a specific RNG seed:
 
 .. code-block::
     :dedent: 0
@@ -245,9 +233,7 @@ plugin commands. This ``seed`` command lets the user pick a specific RNG seed:
             self.rng.seed(seed)
             irc.replySuccess()
 
-For functions that use ``@wrap`` (described further in the
+Command arguments are declared by:
-:ref:`Using commands.wrap tutorial <using-wrap>`), additional command arguments
-are handled by:
 
 1. Adding :ref:`type converters <wrap-converter-list>`, one for each parameter,
    to the list passed into ``@wrap``
@@ -256,12 +242,12 @@ are handled by:
    ``def seed(self, irc, msg, args)``)
 
 We also modify the docstring to document this function. Note the syntax
-on the first line: by convention, required arguments go in ``<>`` and optional
+on the first line: :ref:`by convention <help-syntax>`, required arguments go in ``<>`` and optional
 arguments should be surrounded by ``[]``.
 
 The function body includes a new method
 :py:meth:`irc.replySuccess <supybot.callbacks.RichReplyMethods.replySuccess>`.
-This is just a generic "I succeeded" command which responds with whatever the
+This is a generic "I succeeded" command which responds with whatever the
 bot owner has configured in ``config supybot.replies.success``.
 Also, by using ``@wrap``, we don't need to do any type checking inside the
 function itself - this is handled separately, and invalid argument values will
@@ -272,7 +258,7 @@ we'll go include some more examples to illustrate common patterns.
 
 Command handler with list-type arguments
 ----------------------------------------
-The next sample command is named ``sample`` (no pun intended): it takes a random
+The next command is named ``sample``: it takes a random
 sample of arbitrary size from a list provided by the user:
 
 .. code-block::
@@ -313,7 +299,7 @@ Also, ``irc.error()`` with no text will return a generic error message
 configured in ``supybot.replies.error``, but this is not a valid call to
 :py:meth:`irc.reply <supybot.callbacks.ReplyIrcProxy.reply>`.
 
-``utils.str.commaAndify`` is a simple helper that takes a list of strings
+``utils.str.commaAndify`` is a helper that takes a list of strings
 and turns it into "item1, item2, item3, item4, and item5" for an arbitrary
 length. Limnoria has accumulated many such helpers in its lifetime, many of
 which are described in the :ref:`Using Utils <using-utils>` page.
@@ -344,8 +330,9 @@ documentation too: common ones include ``private=True``, which
 forces a private message, and ``notice=True``, which forces the reply to use
 NOTICE instead of PRIVMSG.
 
-test.py
+.. _test-py:
-=======
+Unit tests (test.py)
+====================
 The easy way to test any plugin would be to start up a bot, load the plugin, and
 run all the commands a few times to verify that they work. But this takes time,
 and as a project grows larger, starts to be a tedious and error-prone process...

use/getting_started.rst

@@ -217,6 +217,7 @@ To unload a plugin, there is a corresponding ``unload`` command::
 To find plugins to load, consult the :ref:`Built-in plugins reference <builtin-plugins-reference>`
 or the Plugins list on `limnoria.net <https://limnoria.net/plugins.xhtml>`_.
 
+.. _help-syntax:
 Understanding the help syntax
 =============================