Expand plugins documentation to multiple pages

[simonw]

I think the plugins docs need to extend beyond a single page now. I want to add a whole section on writing tests for plugins, showing how httpx can be used as seen in simonw/datasette-atom#3 and suchlike.

[simonw]

Current plugin docs: https://datasette.readthedocs.io/en/0.37/plugins.html

[simonw]

Suggested pages:

• plugins/tutorial.html
• plugins/hooks.html
• plugins/testing.html
• plugins/packaging.html

[simonw]

The tutorial should start by taking about development environments - how to get a new fresh copy of Datasette that you can start hacking plugins for, in a fresh virtual environment.

It should then explain the --plugins-dir mechanism, and show how to use it to create a simple plugin that adds a custom SQL function.

Does --reload work against plugins in the plugins/ directory? It should.

Then it should demonstrate a more complex plugin that uses the datasette argument to render a template.

It should promote the next page which lists the plugin hooks.

The hooks page should include links next to each hook to examples of plugins that use them.

The packaging page can explain setup.py for distributing packages (let's not bother explaining single modules) and also needs to show how to bundle package data such as templates.

It should also show how to use pip install -e .[test] for development, and mention that this works with --reload.

[simonw]

Eventually I can also document what to do if your plugin needs to include its own CLI tool. I'm goong it show how to ship a CLI tool with the same name as the plugin using Click and setup.py.

[simonw]

The tutorial can start by showing how to use the new cookiecutter template from #642.

[simonw]

I think I want the "Plugin hooks" page to be top-level, parallel to "Plugins" and "Internals for Plugins". It's the page of documentation refer to most often so I don't want to have to click down a hierarchy from the side navigation to find it.

[simonw]

So the new plan is NOT to have a plugins/ folder, but instead have several top-level pages:

• Plugins (exists)
• Writing plugins
• Plugin hooks
• Testing plugins
• Internals for plugins (exists)

[simonw]

I'm going to break out the plugin hooks first in a single commit to make for a cleaner commit history (since that way git can hopefully detect that the content moved).

[simonw]

Maybe add this to the plugins.rst page near the top:

.. toctree::
   :caption: See also
   :maxdepth: 1

   plugin_hooks
   internals

[simonw]

Now split into four pages:

• https://datasette.readthedocs.io/en/latest/plugins.html
• https://datasette.readthedocs.io/en/latest/writing_plugins.html
• https://datasette.readthedocs.io/en/latest/plugin_hooks.html
• https://datasette.readthedocs.io/en/latest/internals.html

Still need to add the "Testing plugins" page, then I can close this issue.

I should also do #855, documenting the new datasette-plugin cookiecutter template. That can go in writing_plugins.rst.

[simonw]

https://datasette.readthedocs.io/en/latest/testing_plugins.html