docs: basic tutorials

[Exirel]

Description

This starts a new set of tutorials for Plugin Author:

• "Your first plugin" introduce the very concept of a Plugin
• "Playing with your command" talks about commands and triggers
• "Configuration and plugin setup" adds the plugin config section

Combined, they provide a first introduction to Sopel Plugin development. They don't talk about everything, trying to introduce very few notions at the same time.

Further tutorials would be welcome in future release of Sopel.

Checklist

• I have read CONTRIBUTING.md
• I can and do license this contribution under the EFLv2
• No issues are reported by make qa (runs make quality and make test)
• I have tested the functionality of the things this change touches

[dgw]

Who would have expected this many line notes in such a small PR? Well, probably half of them are just slaying the nemesiS, so it's not that bad. 😛

[Exirel]

@dgw I added an introduction in the tutorial root page, because I felt that something was missing. I wanted to tell our reader that 1. they need to know a bit of Python, and 2. writing a plugin is doable, but not all plugin are easy to write!

Apart from this addition, I standardized the plugin name (myplugin.py, MyPluginSection), and use custom label for :doc: links.

I also added a few sentences here and there. In particular, something about the usage of regex. I don't want to overload the reader with too much information about regexes, but a few lines felt better than nothing.

[dgw]

Round two complete, I guess. This is shaping up really nicely!

[SnoopJ]

Nicely done!

[Exirel]

Before diving into the exact details of the review, I feel like you both (@dgw and @SnoopJ) want to add more accurate information, but I don't think it's a good idea. This is a tutorial, and not an exact guide. In my mind, it is not supposed to be 100% accurate on what is and what isn't possible, and it should not explain how things work under the hood.

What is important to me in this tutorial:

• having a different tone than the rest of the documentation, with a more personal approach (using "you" and "we", instead of a more impersonal description of things as in the rest of the documentation)
• providing quick and short examples that can be copy and paste without having to read through comments
• using asserting sentences, like "do that and do this"
• avoid technical details about Python or Sopel, unless they are strictly necessary to understand the current step of the tutorial

The last point is really important to me, as it allows the tutorial to be short and concise. Whenever a notion can be explore more in-depth, I prefer to rely on links and a final section to provide the appropriate pointers. If something is not well explained in the documentation, it is not the role of the tutorial to fix that: it should be fixed in the appropriate topic section, or the correct reference guide.

That is to say: while I appreciate the feedback, I don't want to argue on every single comments of the review when I feel like it's not a matter of correctness and more a matter of perspective.

[dgw]

I feel like you both (@dgw and @SnoopJ) want to add more accurate information

If you mean "more complete", then we have something to discuss. We always want "accurate" (correct) information in the tutorials, i.e. nothing in the tutorial should be wrong or misleading.

If you fixup and resolve the threads about correctness/grammar/phrasing, @SnoopJ and I can then go over the bigger-picture stuff that's left over afterward? (I'm not going to be doing much of this stuff from the highway this week, anyway, I suspect.)

[Exirel]

If you mean "more complete", then we have something to discuss.

Did the fix about the thing and now I think you can read the full tutorial and see what's missing while keeping in mind the flow of each chapter.

[dgw]

I didn't go super ham on this because (as you'll see in a line note) I think this is more of a stepping stone than "final" tutorials we won't want to touch for another five years.

[dgw]

I took a different approach this time, reading through the rendered pages on our deploy preview. Really, there are only a couple of things I'd change now. I've tried to make it as easy as possible with suggestions you can apply through GitHub's GUI.

Meanwhile, I'll leave it to @SnoopJ to explain what he meant earlier today on IRC by saying the tutorials are a "big question mark", if he wants to.

[Exirel]

Really, there are only a couple of things I'd change now.

Great! I applied them all, so it's only a mater of a squash now.

explain what he meant earlier today on IRC by saying the tutorials are a "big question mark"

IIRC it's something like "that's the only thing left to do". But I just added a PR for even more docs so...

[dgw]

I say squash at your leisure. Don't know what's up with Coveralls check statuses getting stuck on Pending, but if we're lucky the squashed history will have enough of whatever it takes to get that to report correctly. (The earlier commits on this branch did, after all.)

[Exirel]

Hey it worked for coverall! 😁

[dgw]

Indeed it did work for Coveralls. But you lost some of the changes in your squash 😩, at least the ones that were just applied right before you did it.

I don't have a7cfd28 locally, but I did have its parent commit (), so I was able to reset the branch. I'll reapply the changes.

[dgw]

Oh yeah, I have to actually approve this now that it's squashed properly.

If you want to --amend the HEAD commit so it'll be verified/signed, feel free. Just please don't rebase again and lose more changes. 😜