Repository: netbox-community/netbox
Pull request: Closes #10696: Break out instructions for installing & removing plugins
### Fixes: #10696

- Move the installation & removal instructions to separate pages
- Add running `manage.py reindex` to the removal instructions (to address #15635)

Problem statement:
Document general instructions for removing an installed plugin
### Change Type

Addition

### Area

Plugins

### Proposed Changes

Extend the plugins documentation to include general instructions for removing an installed plugin. This includes:

* Removing the plugin and its configuration
* Uninstalling the plugin packages (and optionally any dependencies which are no longer needed)
* Dropping any associated tables from the database

Of course, each plugin may require additional work to fully remove it from a NetBox instance depending on its nature, but this should cover the majority of it.

Hints from issue discussion:
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. **Do not** attempt to circumvent this process by "bumping" the issue; doing so will result in its immediate closure and you may be barred from participating in any future discussions. Please see our [contributing guide](https://github.com/netbox-community/netbox/blob/develop/CONTRIBUTING.md).

Commit message: Closes #10696: Break out instructions for installing & rmeoving plugins

Patch to review:
diff --git a/docs/plugins/index.md b/docs/plugins/index.md
index 39314187b48..0f502c5d82f 100644
--- a/docs/plugins/index.md
+++ b/docs/plugins/index.md
@@ -2,6 +2,8 @@
 
 Plugins are packaged [Django](https://docs.djangoproject.com/) apps that can be installed alongside NetBox to provide custom functionality not present in the core application. Plugins can introduce their own models and views, but cannot interfere with existing components. A NetBox user may opt to install plugins provided by the community or build his or her own.
 
+Please see the documented instructions for [installing a plugin](./installation.md) to get started.
+
 ## Capabilities
 
 The NetBox plugin architecture allows for the following:
@@ -23,122 +25,3 @@ Either by policy or by technical limitation, the interaction of plugins with Net
 * **Override core templates.** Plugins can inject additional content where supported, but may not manipulate or remove core content.
 * **Modify core settings.** A configuration registry is provided for plugins, however they cannot alter or delete the core configuration.
 * **Disable core components.** Plugins are not permitted to disable or hide core NetBox components.
-
-## Installing Plugins
-
-The instructions below detail the process for installing and enabling a NetBox plugin.
-
-### Install Package
-
-Download and install the plugin package per its installation instructions. Plugins published via PyPI are typically installed using pip. Be sure to install the plugin within NetBox's virtual environment.
-
-```no-highlight
-$ source /opt/netbox/venv/bin/activate
-(venv) $ pip install <package>
-```
-
-Alternatively, you may wish to install the plugin manually by running `python setup.py install`. If you are developing a plugin and want to install it only temporarily, run `python setup.py develop` instead.
-
-### Enable the Plugin
-
-In `configuration.py`, add the plugin's name to the `PLUGINS` list:
-
-```python
-PLUGINS = [
-    'plugin_name',
-]
-```
-
-### Configure Plugin
-
-If the plugin requires any configuration, define it in `configuration.py` under the `PLUGINS_CONFIG` parameter. The available configuration parameters should be detailed in the plugin's README file.
-
-```no-highlight
-PLUGINS_CONFIG = {
-    'plugin_name': {
-        'foo': 'bar',
-        'buzz': 'bazz'
-    }
-}
-```
-
-### Run Database Migrations
-
-If the plugin introduces new database models, run the provided schema migrations:
-
-```no-highlight
-(venv) $ cd /opt/netbox/netbox/
-(venv) $ python3 manage.py migrate
-```
-
-### Collect Static Files
-
-Plugins may package static files to be served directly by the HTTP front end. Ensure that these are copied to the static root directory with the `collectstatic` management command:
-
-```no-highlight
-(venv) $ cd /opt/netbox/netbox/
-(venv) $ python3 manage.py collectstatic
-```
-
-### Restart WSGI Service
-
-Restart the WSGI service and RQ workers to load the new plugin:
-
-```no-highlight
-# sudo systemctl restart netbox netbox-rq
-```
-
-## Removing Plugins
-
-Follow these steps to completely remove a plugin.
-
-### Update Configuration
-
-Remove the plugin from the `PLUGINS` list in `configuration.py`. Also remove any relevant configuration parameters from `PLUGINS_CONFIG`.
-
-### Remove the Python Package
-
-Use `pip` to remove the installed plugin:
-
-```no-highlight
-$ source /opt/netbox/venv/bin/activate
-(venv) $ pip uninstall <package>
-```
-
-### Restart WSGI Service
-
-Restart the WSGI service:
-
-```no-highlight
-# sudo systemctl restart netbox
-```
-
-### Drop Database Tables
-
-!!! note
-    This step is necessary only for plugin which have created one or more database tables (generally through the introduction of new models). Check your plugin's documentation if unsure.
-
-Enter the PostgreSQL database shell to determine if the plugin has created any SQL tables. Substitute `pluginname` in the example below for the name of the plugin being removed. (You can also run the `\dt` command without a pattern to list _all_ tables.)
-
-```no-highlight
-netbox=> \dt pluginname_*
-                   List of relations
-                   List of relations
- Schema |       Name     | Type  | Owner
---------+----------------+-------+--------
- public | pluginname_foo | table | netbox
- public | pluginname_bar | table | netbox
-(2 rows)
-```
-
-!!! warning
-    Exercise extreme caution when removing tables. Users are strongly encouraged to perform a backup of their database immediately before taking these actions.
-
-Drop each of the listed tables to remove it from the database:
-
-```no-highlight
-netbox=> DROP TABLE pluginname_foo;
-DROP TABLE
-netbox=> DROP TABLE pluginname_bar;
-DROP TABLE
-```
diff --git a/docs/plugins/installation.md b/docs/plugins/installation.md
new file mode 100644
index 00000000000..ffea5d42deb
--- /dev/null
+++ b/docs/plugins/installation.md
@@ -0,0 +1,68 @@
+# Installing a Plugin
+
+!!! warning
+    The instructions below detail the general process for installing and configuring a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin **before** attempting to install it.
+
+## Install the Python Package
+
+Download and install the plugin's Python package per its installation instructions. Plugins published via PyPI are typically installed using the [`pip`](https://packaging.python.org/en/latest/tutorials/installing-packages/) command line utility. Be sure to install the plugin within NetBox's virtual environment.
+
+```no-highlight
+$ source /opt/netbox/venv/bin/activate
+(venv) $ pip install <package>
+```
+
+Alternatively, you may wish to install the plugin manually by running `python setup.py install`. If you are developing a plugin and want to install it only temporarily, run `python setup.py develop` instead.
+
+## Enable the Plugin
+
+In `configuration.py`, add the plugin's name to the `PLUGINS` list:
+
+```python
+PLUGINS = [
+    # ...
+    'plugin_name',
+]
+```
+
+## Configure the Plugin
+
+If the plugin requires any configuration, define it in `configuration.py` under the `PLUGINS_CONFIG` parameter. The available configuration parameters should be detailed in the plugin's `README` file or other documentation.
+
+```no-highlight
+PLUGINS_CONFIG = {
+    'plugin_name': {
+        'foo': 'bar',
+        'buzz': 'bazz'
+    }
+}
+```
+
+## Run Database Migrations
+
+If the plugin introduces new database models, run the provided schema migrations:
+
+```no-highlight
+(venv) $ cd /opt/netbox/netbox/
+(venv) $ python3 manage.py migrate
+```
+
+!!! tip
+    It's okay to run the `migrate` management command even if the plugin does not include any migration files.
+
+## Collect Static Files
+
+Plugins may package static resources like images or scripts to be served directly by the HTTP front end. Ensure that these are copied to the static root directory with the `collectstatic` management command:
+
+```no-highlight
+(venv) $ cd /opt/netbox/netbox/
+(venv) $ python3 manage.py collectstatic
+```
+
+### Restart WSGI Service
+
+Finally, restart the WSGI service and RQ workers to load the new plugin:
+
+```no-highlight
+# sudo systemctl restart netbox netbox-rq
+```
diff --git a/docs/plugins/removal.md b/docs/plugins/removal.md
new file mode 100644
index 00000000000..a0f33a2e0b6
--- /dev/null
+++ b/docs/plugins/removal.md
@@ -0,0 +1,66 @@
+# Removing a Plugin
+
+!!! warning
+    The instructions below detail the general process for removing a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin **before** attempting to remove it.
+
+## Disable the Plugin
+
+Disable the plugin by removing it from the `PLUGINS` list in `configuration.py`.
+
+## Remove its Configuration
+
+Delete hte plugin's entry (if any) in the `PLUGINS_CONFIG` dictionary in `configuration.py`.
+
+!!! tip
+    If there's a chance you may reinstall the plugin, consider commenting out any configuration parameters instead of deleting them.
+
+## Re-index Search Entries
+
+Run the `reindex` management command to reindex the global search engine. This will remove any stale entries pertaining to objects provided by the plugin.
+
+## Uninstall its Python Package
+
+Use `pip` to remove the installed plugin:
+
+```no-highlight
+$ source /opt/netbox/venv/bin/activate
+(venv) $ pip uninstall <package>
+```
+
+## Restart WSGI Service
+
+Restart the WSGI service:
+
+```no-highlight
+# sudo systemctl restart netbox
+```
+
+## Drop Database Tables
+
+!!! note
+    This step is necessary only for plugins which have created one or more database tables (generally through the introduction of new models). Check your plugin's documentation if unsure.
+
+Enter the PostgreSQL database shell (`manage.py dbshell`) to determine if the plugin has created any SQL tables. Substitute `pluginname` in the example below for the name of the plugin being removed. (You can also run the `\dt` command without a pattern to list _all_ tables.)
+
+```no-highlight
+netbox=> \dt pluginname_*
+                   List of relations
+                   List of relations
+ Schema |       Name     | Type  | Owner
+--------+----------------+-------+--------
+ public | pluginname_foo | table | netbox
+ public | pluginname_bar | table | netbox
+(2 rows)
+```
+
+!!! warning
+    Exercise extreme caution when removing tables. Users are strongly encouraged to perform a backup of their database immediately before taking these actions.
+
+Drop each of the listed tables to remove it from the database:
+
+```no-highlight
+netbox=> DROP TABLE pluginname_foo;
+DROP TABLE
+netbox=> DROP TABLE pluginname_bar;
+DROP TABLE
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index e1128578acd..c04ef519f47 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -127,7 +127,9 @@ nav:
         - Synchronized Data: 'integrations/synchronized-data.md'
         - Prometheus Metrics: 'integrations/prometheus-metrics.md'
     - Plugins:
-        - Using Plugins: 'plugins/index.md'
+        - About Plugins: 'plugins/index.md'
+        - Installing a Plugin: 'plugins/installation.md'
+        - Removing a Plugin: 'plugins/removal.md'
         - Developing Plugins:
             - Getting Started: 'plugins/development/index.md'
             - Models: 'plugins/development/models.md'


Code review comments:
diff_hunk: @@ -0,0 +1,66 @@
+# Removing a Plugin
+
+!!! warning
+    The instructions below detail the general process for removing a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin **before** attempting to remove it.
+
+## Disable the Plugin
+
+Disable the plugin by removing it from the `PLUGINS` list in `configuration.py`.
+
+## Remove its Configuration
+
+Delete hte plugin's entry (if any) in the `PLUGINS_CONFIG` dictionary in `configuration.py`.
path: docs/plugins/removal.md
text: @user1:
hte -> the