Plugin docs restructure of content (napari#203)

# Description
I've reorganised the content of /plugins following napari#153. I'm interested
to see what you think!
I was very heavy handed with the use of grids for the index pages,
because they are the best I could think of. Open to other options as
always.

I also fixed a small number links on other pages outside of /plugins
because I broke a lot of links with this restructure and I wasn't
exactly sure what I caused and what was already broken - thought it was
safer to just fix them.

Here is what the homepage of plugins would look like:

![image](https://github.com/napari/docs/assets/21295664/f4d732a3-d485-4186-89e7-1f40a7d93c96)

## Type of change
- [x] Fixes or improves existing content
- [x] Adds new content page(s)

## Final checklist:
- [x] My PR is the minimum possible work for the desired functionality

## Addendum

A small number of my commits got associated with my bot account (I set
the wrong email in my git config because I deleted my config before
creating napari#201 🙈). I genuinely don't know how to fix that. If it is going
to be an issue I could make a new branch and squash all the commits into
one big commit from my seankmartin account.

Author: seankmartin

docs/_toc.yml

@@ -75,32 +75,48 @@ subtrees:
   - file: plugins/index
     subtrees:
     - entries:
-      - file: plugins/find_and_install_plugin
-      - file: plugins/first_plugin
-      - file: plugins/manifest
-      - file: plugins/contributions
-      - file: plugins/guides
-      - file: plugins/test_deploy
-      - file: plugins/best_practices
-      - file: plugins/debug_plugins
-      - file: plugins/npe2_migration_guide
-      - file: plugins/npe1
-      - file: plugins/testing_workshop_docs/index
+      - file: plugins/start_using_plugins/index
         subtrees:
         - entries:
-          - file: plugins/testing_workshop_docs/1-pythons-assert-keyword
-          - file: plugins/testing_workshop_docs/2-pytest-testing-frameworks
-          - file: plugins/testing_workshop_docs/3-readers-and-fixtures
-          - file: plugins/testing_workshop_docs/4-test-coverage
-          - file: plugins/testing_workshop_docs/testing-resources
-      - file: plugins/virtual_environment_docs/index
+          - file: plugins/start_using_plugins/finding_and_installing_plugins
+      - file: plugins/building_a_plugin/index
         subtrees:
         - entries:
-          - file: plugins/virtual_environment_docs/1-virtual-environments
-          - file: plugins/virtual_environment_docs/2-deploying-your-plugin
-          - file: plugins/virtual_environment_docs/3-version-management
-          - file: plugins/virtual_environment_docs/4-developer-tools
-          - file: plugins/virtual_environment_docs/5-survey
+          - file: plugins/building_a_plugin/first_plugin
+          - file: plugins/building_a_plugin/guides
+          - file: plugins/building_a_plugin/debug_plugins
+          - file: plugins/building_a_plugin/best_practices
+          - file: plugins/virtual_environment_docs/index
+            subtrees:
+            - entries:
+              - file: plugins/virtual_environment_docs/1-virtual-environments
+              - file: plugins/virtual_environment_docs/2-deploying-your-plugin
+              - file: plugins/virtual_environment_docs/3-version-management
+              - file: plugins/virtual_environment_docs/4-developer-tools
+              - file: plugins/virtual_environment_docs/5-survey
+      - file: plugins/testing_and_publishing/index
+        subtrees:
+        - entries:
+          - file: plugins/testing_and_publishing/test
+          - file: plugins/testing_and_publishing/deploy
+          - file: plugins/testing_workshop_docs/index
+            subtrees:
+            - entries:
+              - file: plugins/testing_workshop_docs/1-pythons-assert-keyword
+              - file: plugins/testing_workshop_docs/2-pytest-testing-frameworks
+              - file: plugins/testing_workshop_docs/3-readers-and-fixtures
+              - file: plugins/testing_workshop_docs/4-test-coverage
+              - file: plugins/testing_workshop_docs/testing-resources
+      - file: plugins/advanced_topics/index
+        subtrees:
+        - entries:
+          - file: plugins/advanced_topics/npe2_migration_guide
+          - file: plugins/advanced_topics/npe1
+      - file: plugins/technical_references/index
+        subtrees:
+        - entries:
+          - file: plugins/technical_references/manifest
+          - file: plugins/technical_references/contributions
   - file: community/index
     subtrees:
     - titlesonly: True

docs/developers/documentation/docs_template.md

@@ -144,4 +144,4 @@ words to capitalize in your headings (spoiler - we use sentence case for our hea
 ## Next steps
 - Use this section to link to other (maybe more advanced?) tutorials, further reading on any complex topics you mentioned,
 or other relevant documentation
-- Now that you've written your document, you can proceed with [updating the TOC](./index.md#2-update-toc)
+- Now that you've written your document, you can proceed with [updating the TOC](update-toc)

docs/developers/documentation/index.md

@@ -461,7 +461,7 @@ We will use Ubuntu for this guide since it is the default WSL distribution, easy
 6. You can test that all of this OpenGL setup is working by running `glxgears` from the Ubuntu terminal. You should see a window with some gears spinning.
 7. `sudo apt install fontconfig`.
 8. `pip install pyqt5-tools`.
-9. Fork the napari docs repository and clone it to the same parent folder as the napari repository (see [](#prerequisites)). Then navigate to the napari docs folder via `cd napari-docs`.
+9. Fork the napari docs repository and clone it to the same parent folder as the napari repository (see [](prerequisites)). Then navigate to the napari docs folder via `cd napari-docs`.
 10. Install `make` with `sudo apt install make`.
 11. Run `make docs` or other `make` commands to build the documentation.
 

docs/plugins/advanced_topics/index.md

@@ -0,0 +1,20 @@
+# Advanced Topics
+
+Advanced topics for plugin developers around the deprecated first generation napari plugins, and how to move to the new system.
+
+::::{grid}
+:::{grid-item-card} Migration guide to `npe2`
+:link: npe2-migration-guide
+:link-type: ref
+Have a plugin written for the first generation plugin system? This guide will help you migrate to the new plugin system.
+
+:::
+
+:::{grid-item-card} First generation plugin system
+:link: napari-plugin-engine
+:link-type: ref
+
+A guide to the first generation plugin system. This is now deprecated and should not be used for new plugins.
+
+:::
+::::

docs/plugins/npe1.md renamed to docs/plugins/advanced_topics/npe1.md

@@ -1,5 +1,5 @@
 (napari-plugin-engine)=
-# 1st Gen Plugin Guide (*Deprecated*)
+# First generation plugins (*Deprecated*)
 
 ```{Admonition} DEPRECATED
 :class: warning
@@ -209,7 +209,7 @@ functionality by simply installing your package along with napari:
 (plugin-sharing)=
 ### Step 4: Deploy your plugin
 
-See [testing and deploying](./test_deploy) your plugin.  (This hasn't changed
+See [testing and deploying](plugin-test-deploy) your plugin.  (This hasn't changed
 significantly with the secod generation (`npe2`) plugin engine).
 
 

docs/plugins/npe2_migration_guide.md renamed to docs/plugins/advanced_topics/npe2_migration_guide.md

@@ -1,6 +1,6 @@
 (npe2-migration-guide)=
 
-# `npe2` migration guide
+# Migration to `npe2`
 
 This document details how to convert a plugin using the first generation
 `napari-plugin-engine`, to the new `npe2` format.
@@ -9,8 +9,7 @@ The primary difference between the first generation and second generation plugin
 system relates to how napari *discovers* plugin functionality. In the first
 generation plugin engine, napari had to *import* plugin modules to search for
 hook implementations decorated with `@napari_hook_implementation`. In `npe2`,
-plugins declare their contributions *statically* with a [manifest
-file](./manifest).
+plugins declare their contributions *statically* with a [manifest file](../technical_references/manifest).
 
 ## Migrating using the `npe2` command line tool
 
@@ -77,7 +76,7 @@ Executing `npe2 convert .` will **modify** the current directory!
 The `npe2 convert` command will:
 
 1. Inspect your plugin for hook implementations, and generate an npe2-compatible
-   [manifest file](./manifest), called `napari.yaml`.
+   [manifest file](../technical_references/manifest), called `napari.yaml`.
 2. **Modify** your `setup.cfg` to use the new `napari.manifest` entry point, and
    include the manifest file in your package data.
 
@@ -93,7 +92,7 @@ If you have any napari_plugin_engine imports or hook_implementation decorators,
 ```
 
 You are encouraged to inspect the newly-generated `napari.yaml` file.  Refer to
-the [manifest](./manifest) and [contributions](./contributions) references pages
+the [manifest](../technical_references/manifest) and [contributions](../technical_references/contributions) references pages
 for details on each field in the manifest.
 
 ```{note}
@@ -124,14 +123,14 @@ The next time napari is run, your plugin should be discovered as an
 > *This section goes into detail on the differences between first-generation and
 second-generation implementations. In many cases, this will be more detail than
 you need.  If you are still struggling with a specific conversion after using
-`npe2 convert` and reading the [contributions](./contributions) reference and
-[guides](./guides), this section may be of help.*
+`npe2 convert` and reading the [contributions](../technical_references/contributions) reference and
+[guides](../building_a_plugin/guides), this section may be of help.*
 
 
 Existing `napari-plugin-engine` plugins expose functionality via *hook
 implementations*. These are functions decorated to indicate they fullfil a
 *hook specification* described by napari. Though there are some exceptions,
-most *hook implementations* can be straightforwardly mapped to npe2 [contributions](./contributions)
+most *hook implementations* can be straightforwardly mapped to npe2 [contributions](../technical_references/contributions)
 
 `npe2` provides a command-line tool that will generate plugin manifests by
 inspecting exposed *hook implementations*. Below, we will walk through the
@@ -140,7 +139,7 @@ kinds of migrations `npe2 convert` helps with.
 For each type of *hook specification* there is a corresponding section below
 with migration tips. Each lists the *hook specifications* that are relevant to
 that section and an example manifest. For details, refer to the
-[Contributions references](./contributions).
+[Contributions references](../technical_references/contributions).
 
 ### Readers
 

docs/plugins/_layer_data_guide.md renamed to docs/plugins/building_a_plugin/_layer_data_guide.md

@@ -209,7 +209,7 @@ dedicated to the stability of your plugin. Aim for 100%!
 Of course, simply having 100% coverage doesn't mean your code is bug-free, so
 make sure that you test all of the various ways that your code might be called.
 
-See our [Tips for testing napari plugins](plugin-testing-tips).
+See [Tips for testing napari plugins](plugin-testing-tips).
 
 ### How to check test coverage?
 

docs/plugins/best_practices.md renamed to docs/plugins/building_a_plugin/best_practices.md

@@ -35,7 +35,7 @@ To quickly get started with debugging your plugin, you can do the following:
 4. Run the created napari launch script in debug mode. For example, in VSCode, you can do this by opening the script in the editor, [selecting your napari virtual environment as the python interpreter](https://code.visualstudio.com/docs/python/environments) and then clicking the `Run and Debug` button in the left hand toolbar, selecting `Python: File` as the run configuration.
 5. At a breakpoint or exception (in VSCode, tick the `Raised Exceptions` box in the bottom left under the `Breakpoints` menu to see exceptions) you can then step through the code, inspect variables, and see the state of the napari viewer and your plugin. When you are done done debugging hit the continue button and napari will resume normal execution. See the image below for an example of a napari plugin debugging session in VSCode paused on a breakpoint.
 
-![debugging_in_vscode](../images/vs_code_debug.png)
+![debugging_in_vscode](../../images/vs_code_debug.png)
 
 ## Debugging plugin start-up issues
 
@@ -199,7 +199,7 @@ Running `python reproduce_issue.py` will run our widget for the inputs `False, 0
 
 ## Isolate the issue from napari
 
-This solution ties in with the idea of test-driven development (see the [napari testing guidelines](./test_deploy.md#prefer-smaller-unit-tests-when-possible)). The idea is to trust that napari will provide the information you expect it to, and test your widgets independently of the viewer. In the case above we can verify that input values work as expected like so:
+This solution ties in with the idea of test-driven development (see the [napari testing guidelines](../testing_and_publishing/test.md#prefer-smaller-unit-tests-when-possible)). The idea is to trust that napari will provide the information you expect it to, and test your widgets independently of the viewer. In the case above we can verify that input values work as expected like so:
 
 ```Python
 # test_print.py
@@ -216,7 +216,7 @@ if __name__ == "__main__":
     test_false_inputs()
 ```
 
-Then, for `python test_print.py` you can use any of your usual debugging tools - such as the visual debugger provided by a Python IDE (e.g. PyCharm, VSCode, or Spyder). Further, an isolated test like this can be integrated into a [testing suite for your napari plugin](test_deploy).
+Then, for `python test_print.py` you can use any of your usual debugging tools - such as the visual debugger provided by a Python IDE (e.g. PyCharm, VSCode, or Spyder). Further, an isolated test like this can be integrated into a [testing suite for your napari plugin](plugin-test-deploy).
 
 ## Logging and user messages in napari
 

docs/plugins/debug_plugins.md renamed to docs/plugins/building_a_plugin/debug_plugins.md

@@ -1,4 +1,5 @@
-# Your First Plugin
+(your-first-plugin)=
+# Your first plugin
 
 In this tutorial, we'll step through the fundamental concepts for building a
 **bare minimum** "hello napari" plugin from scratch.
@@ -33,8 +34,8 @@ installing napari.
 
 Napari plugins are just Python packages. *Minimally*, they must:
 
-1. Include a static [plugin manifest](./manifest) file that details the
-   [contributions](./contributions) contained in the plugin.
+1. Include a static [plugin manifest](../technical_references/manifest) file that details the
+   [contributions](../technical_references/contributions) contained in the plugin.
 2. Declare a `napari.manifest` [entry point][entry_points] that allows
    napari to detect the plugin at runtime.
 
@@ -177,7 +178,7 @@ autogeneration capabilities to turn this function into a widget)*
 ### Add a `napari.yaml` manifest
 
 
-If you haven't already, create an empty [plugin manifest](./manifest) file at `napari_hello/napari.yaml`
+If you haven't already, create an empty [plugin manifest](../technical_references/manifest) file at `napari_hello/napari.yaml`
 We will use this file to tell napari:
 
 1. That our plugin contributes a [**command**](contributions-commands)
@@ -293,11 +294,11 @@ cookiecutter https://github.com/napari/cookiecutter-napari-plugin
 
 Plugins can do a lot more than just say hi!  You can see the complete list
 of available contributions and their fields in the
-[Contributions Reference](./contributions), and learn more about each
-specific contribution type in the [Guides](./guides).
+[Contributions Reference](../technical_references/contributions), and learn more about each
+specific contribution type in the [Guides](../building_a_plugin/guides).
 
-Review the [Best Practices](./best_practices) when developing plugins and,
-when you're ready to share your plugin, see [Testing and Deployment](./test_deploy).
+Review the [Best Practices](../building_a_plugin/best_practices) when developing plugins and,
+when you're ready to share your plugin, see [Testing and Publishing](../testing_and_publishing/index).
 
 [miniconda]: https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html
 [python_env]: https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-python

docs/plugins/first_plugin.md renamed to docs/plugins/building_a_plugin/first_plugin.md

@@ -1,25 +1,26 @@
-# Contribution Guides
+(plugin-contribution-guides)=
+# Plugin contributions
 
 This page provides guides on many of the plugin contribution patterns.
 Each provides a general overview of the purpose of the contribution and
 an example implementation. For details on the type and meaning of each
 field in a specific contribution, See the
-[contributions reference](./contributions)
+[contributions reference](../technical_references/contributions)
 
 
-```{include} _npe2_readers_guide.md
+```{include} ../_npe2_readers_guide.md
 ```
 ----------------
 
-```{include} _npe2_writers_guide.md
+```{include} ../_npe2_writers_guide.md
 ```
 ----------------
 
-```{include} _npe2_widgets_guide.md
+```{include} ../_npe2_widgets_guide.md
 ```
 ----------------
 
-```{include} _npe2_sample_data_guide.md
+```{include} ../_npe2_sample_data_guide.md
 ```
 ----------------
 

docs/plugins/guides.md renamed to docs/plugins/building_a_plugin/guides.md

@@ -0,0 +1,66 @@
+(how-to-build-a-plugin)=
+# Building a plugin
+
+Plugins allow developers to customize and extend napari.  This includes
+
+- Adding file format support with [readers] and [writers]
+- Adding custom [widgets] and user interface elements
+- Providing [sample data][sample_data]
+- Changing the look of napari with a color [theme]
+
+::::{grid}
+:::{grid-item-card} Your first plugin
+:link: your-first-plugin
+:link-type: ref
+If you're just getting started with napari plugins, try our tutorial to build your first plugin!
+
+:::
+
+:::{grid-item-card} Plugin functionality
+:link: plugin-contribution-guides
+:link-type: ref
+
+New pieces of functionality are termed contributions. To understand what plugins can add to napari, see the plugin contributions guide.
+
+:::
+::::
+
+::::{grid}
+:::{grid-item-card} Best practices
+:link: best-practices
+:link-type: ref
+
+There are a few best practices to keep in mind when building a plugin. See the best practices guide for details.
+
+:::
+
+:::{grid-item-card} Testing and publishing
+:link: plugin-test-deploy
+:link-type: ref
+
+Testing your plugin is an important step before publishing. Once your plugin is ready, you can publish it to PyPI, conda-forge and the napari-hub. See the testing and publishing guide for details.
+:::
+::::
+
+```{admonition} Introducing npe2
+:class: important
+
+We introduced a new plugin engine [`npe2`][npe2] in December 2021.
+
+Unless otherwise stated, most of the documentation herein pertains
+to the new npe2 format (which uses a static `napari.yaml` manifest)
+
+Plugins targeting the first generation `napari-plugin-engine` 
+(using `@napari_hook_implementation` decorators, see [npe1]) will
+continue to work for at least the first half of 2022, but we
+recommend migrating to `npe2`. See the
+[migration guide](npe2-migration-guide) for details.
+```
+
+[npe1]: https://github.com/napari/napari-plugin-engine
+[npe2]: https://github.com/napari/npe2
+[readers]: contributions-readers
+[writers]: contributions-writers
+[widgets]: contributions-widgets
+[sample_data]: contributions-sample-data
+[theme]: contributions-themes