docs(plugin): Update plugin installation examples (#22185)

docs/configuration/system.md

@@ -57,7 +57,7 @@ In order to send email, NetBox needs an email server configured. The following i
 Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) function accessible within the NetBox shell:
 
 ```no-highlight
-# python ./manage.py nbshell
+(venv) $ python3 ./manage.py nbshell
 >>> from django.core.mail import send_mail
 >>> send_mail(
   'Test Email Subject',

docs/plugins/installation.md

@@ -7,12 +7,32 @@
 
 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.
 
+For production installations, the recommended method is to add the package to `/opt/netbox/local_requirements.txt` and then run NetBox's upgrade script. This installs the plugin as part of the standard NetBox installation and upgrade process and ensures that it will be reinstalled if the virtual environment is rebuilt.
+
+```no-highlight
+$ sudo sh -c "echo '<package>' >> /opt/netbox/local_requirements.txt"
+$ sudo /opt/netbox/upgrade.sh
+```
+
+Installing packages into NetBox's virtual environment requires write permissions to that directory. For installations under `/opt/netbox`, a regular user typically does not have write permissions. Activating the virtual environment does not change file permissions, so a direct `pip install` command may result in a `Permission denied` error.
+
+If you must install a package manually, use one of the following methods. You can switch to a root shell before activating the virtual environment:
+
 ```no-highlight
-$ source /opt/netbox/venv/bin/activate
-(venv) $ pip install <package>
+$ sudo -i
+# 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.
+Or, run `pip` by invoking the Python executable within NetBox's virtual environment:
+
+```no-highlight
+$ sudo /opt/netbox/venv/bin/python3 -m pip install <package>
+```
+
+In the examples above, `$` indicates a regular user shell and `#` indicates a root shell.
+
+Packages that are not published to PyPI may need to be installed from a local source tree. From the package directory, use one of the methods above to run `pip install .`; for editable development installs, run `pip install --editable .` instead.
 
 ## Enable the Plugin
 
@@ -38,13 +58,16 @@ PLUGINS_CONFIG = {
 }
 ```
 
+!!! note
+    If you ran `/opt/netbox/upgrade.sh` after enabling and configuring the plugin, the script has already applied database migrations and collected static files. If you ran it only to install the package before enabling the plugin, continue with the migration and static file steps below.
+
 ## 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
+(venv) $ cd /opt/netbox/
+(venv) $ python3 netbox/manage.py migrate
 ```
 
 !!! tip
@@ -55,14 +78,14 @@ If the plugin introduces new database models, run the provided schema migrations
 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
+(venv) $ cd /opt/netbox/
+(venv) $ python3 netbox/manage.py collectstatic
 ```
 
-### Restart WSGI Service
+## Restart WSGI Service
 
 Finally, restart the WSGI service and RQ workers to load the new plugin:
 
 ```no-highlight
-# sudo systemctl restart netbox netbox-rq
+$ sudo systemctl restart netbox netbox-rq
 ```

docs/plugins/removal.md

@@ -19,18 +19,19 @@ Delete the plugin's entry (if any) in the `PLUGINS_CONFIG` dictionary in `config
 Run the `reindex` management command to reindex the global search engine. This will remove any stale entries pertaining to objects provided by the plugin.
 
 ```no-highlight
-$ cd /opt/netbox/netbox/
+$ cd /opt/netbox/
 $ source /opt/netbox/venv/bin/activate
-(venv) $ python3 manage.py reindex
+(venv) $ python3 netbox/manage.py reindex
 ```
 
 ## Uninstall its Python Package
 
-Use `pip` to remove the installed plugin:
+If the plugin was installed by adding it to `/opt/netbox/local_requirements.txt`, remove its package entry from that file first. Otherwise, the package will be reinstalled the next time NetBox's upgrade script is run.
+
+Use `pip` to remove the installed plugin from NetBox's virtual environment:
 
 ```no-highlight
-$ source /opt/netbox/venv/bin/activate
-(venv) $ pip uninstall <package>
+$ sudo /opt/netbox/venv/bin/python3 -m pip uninstall <package>
 ```
 
 ## Restart WSGI Service
@@ -38,7 +39,7 @@ $ source /opt/netbox/venv/bin/activate
 Restart the WSGI service:
 
 ```no-highlight
-# sudo systemctl restart netbox
+$ sudo systemctl restart netbox
 ```
 
 ## Drop Database Tables
@@ -150,5 +151,5 @@ stale_types.delete()
 After making these changes, restart the NetBox service to ensure all changes are reflected.
 
 ```no-highlight
-sudo systemctl restart netbox
+$ sudo systemctl restart netbox
 ```