docs: the plugin chapter

[Exirel]

Description

I moved the content of source/plugin.rst to source/plugin/*.rst files and then worked around that structure:

• a glossary
• what is a plugin (explain what it is, plugin types, and plugin name)
• anatomy of a plugin (plugin callables, jobs, setup & shutdown, and about plugin configuration)
• interact with the bot (how to use bot to talk, join channels, and stuffs)
• sopel.plugin (plugin decorators, already explained in anatomy of a plugin)
• sopel.plugins (internals, no need to touch that)

I took the same approach I used for the core configuration: one part is a thorough explanation of the topic and the other part is the good old autodoc. I really like it!

I think it's possible to do even more, and that should be done later, either by me or someone else, in this version or a future one. The most important here is that I think it's a good structure to work with.

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

[Exirel]

@dgw if by chance you have the time to review some documentation, I think I'm more or less done with:

• the glossary
• What is a plugin
• Anatomy of a plugin

That last one in particular: I took the same approach I had with the configuration, i.e. "Anatomy of a plugin" is an exploration of everything around a plugin and its rules (which is at the core of any plugin), and I left the autodoc part in another section. I really like how it turned out, but you know how poor my English can be.

The next steps in that documentation PR are probably about how to use the bot and the trigger arguments, because having to read the whole API documentation for that is not fun, and I've seen many questions about how to do X or Y because the answers are usually buried deep into the code, or fragmented across multiple docstrings.

[dgw]

I did indeed find time to review this, somehow, despite getting almost no time to myself all day. Too bad for you, though—there are a lot of line notes! 😝

[dgw]

Whipped through here again right before my next meeting. Hopefully I answered all the little sub-threads that needed it, so you can proceed with your next steps. 😸

[Exirel]

Added some documentation about the bot parameter for plugin callables. I think it'll be a great place to add information asked by users. A lot of the times we had questions, I wished we could have some place to put the answers, and I think this new structure for the documentation will be the right place.

[Exirel]

@dgw brace yourself, it's the real one now. I haven't added that many things, and yet, I'm sure you'll find plenty to fix.

[dgw]

Did not expect this many line notes in another go-around, but here we are. Have fun! 😅

I'm also thinking about the URL structure, but it's not clear to me that /docs/plugin/ (or /docs/plugin/index.html) would be meaningfully better than /docs/plugin.html. Am also thinking about whether to make it /docs/plugin/* (current PR) or /docs/plugins/*… The singular matches the Sopel submodule that plugin devs work with the most, I guess.

[dgw]

New alternative suggestion, since we haven't gotten around to having this conversation yet… (sadly)

Suggested change

	* you don't have any dependencies other than Sopel and the Python's built-in
	library
	* you don't have any dependencies other than Sopel and Python's built-in library,
	or your plugin is a "one-off" for your use only (not intended to be shared)

I still don't see why we'd mention dependencies for this, but not the Folder type.

[Exirel]

Did not expect this many line notes in another go-around, but here we are. Have fun! sweat_smile

I added a whole new section, that checks out.

The singular matches the Sopel submodule that plugin devs work with the most, I guess.

Both work for me, so your call! It's one git mv away so pretty easy.

[dgw]

@Exirel I've seen the fixes since my last review, finally. Go ahead and squash/rebase, then I'll re-review one more time before hopefully merging. There can't be many typos left by now! 😅

[Exirel]

<loud happy noise>

[Exirel]

Done!

[Exirel]

@dgw I've added a new commit with some minor changes, to address the dependencies question. I added that it is better not to have dependencies, because it is more difficult to share the plugin. I added a note to tell plugin authors to write the list of dependencies in a requirements.txt file and to document them. I hope this will clarify what I meant.

I still think Folder plugins are not a good idea, as you need to add a directory to the sys.path, which is bad.
I added the information about dependencies, with the note, so I believe this problem is addressed too.

[dgw]

I'm doing my best to make good suggestions for these new notes now, so you can incorporate them (or get inspired and make your own changes) before going to bed tonight in CEST. 😸 Then I have a prayer of doing that full re-review while you sleep. 😁

[Exirel]

@dgw if I didn't miss anything, we should be good now!

[dgw]

I think we can finish this over the weekend! Home stretch! Glad I did one last full re-review, though. Caught a few stupid typos that I missed the first n times around. x)

[Exirel]

@dgw I'm ready to rebase & squash asap.

[dgw]

Go for it! 🐑

[Exirel]

After ~150 comments and many reviews, I've rebased & squashed the whole thing. I'm quite proud of this work, and I hope this will open the path for even greater documentation in the future.

Ready to merge!