Document the types of plugins and expected results

[jdevera]

What is covered in this PR

I have recently attempted to write a plugin for Flake8. I found the video tutorial to be a great source of info, but understand it is desirable to move more and more of its contents to written form.

This PR is my attempt at moving some of that information to the docs.

Note this is based on my understanding after watching the video tutorial and having read the code to understand the different types of plugins, how they are loaded, how they are called, what parameters they get and what Flake8 expects them to return.

One notable omission

When describing the physical line plugins, I have deliberately omitted the fact that it supports receiving a single tuple from the plugin. I am basing this omission on my intuition that this is a special case to deal with legacy, one that Flake8 might not want to promote.

[asottile]

hi -- appreciate the work you put into this but it breaks the links and I don't think it really makes things "better" -- the emoji in the description also make this PR look like spam so maybe keep that in mind for the future

[jdevera]

Removed emojis from the description (worth adding to the contributing docs since emoji are pretty common in legit non-spammy uses).

With that noise out of the way...

What are the broken links that concern you?

But more importantly, can you please elaborate on this not making things better? I'm happy to rework it, as I intended this as a first iteration.

[asottile]

any time content is moved or pages are split or headings are changed the links break -- also this info is already in docs/source/plugin-development/plugin-parameters.rst

[jdevera]

Okay I see. I did read the docs and watched the video and found I still had to look at the code a lot to understand what was going on and what was expected of a plugin, and the different options.

This is to state that, from my perspective as a plugin developer, the docs could be improved to lower further the barrier of entry.

From your comments, I understand you do not wish to accept this PR or possible reworks, so I'll just drop it. Let me know if I got that wrong.

Additionally, if keeping the structure of the current doc is a requirement, it is something else that could be mentioned in the contribution guidelines. My belief is that such a requirement hinders the rate of improvement, but I respect different priorities than mine.