Initial documentation for plugins framework

docs/configuration/optional-settings.md

@@ -299,6 +299,24 @@ Determine how many objects to display per page within each list of objects.
 
 ---
 
+## PLUGINS_CONFIG
+
+Default: Empty
+
+This parameter holds configuration settings for individual NetBox plugins. It is defined as a dictionary, with each key using the name of an installed plugin. The specific parameters supported are unique to each plugin: Reference the plugin's documentation to determine the supported parameters.
+
+Note that `PLUGINS_ENABLED` must be set to True for this to take effect.
+
+---
+
+## PLUGINS_ENABLED
+
+Default: `False`
+
+Enable [NetBox plugins](../../plugins/).
+
+---
+
 ## PREFER_IPV4
 
 Default: False

docs/plugins/development.md

@@ -0,0 +1,58 @@
+# Plugin Development
+
+This documentation covers the development of custom plugins for NetBox. Plugins are essentially self-contained [Django apps](https://docs.djangoproject.com/en/stable/) which integrate with NetBox to provide custom functionality. Since the development of Django apps is already very well-documented, we'll only be covering the aspects that are specific to NetBox.
+
+## Initial Setup
+
+### Plugin Structure
+
+Although the specific structure of a plugin is largely left to the discretion of its authors, a typical NetBox plugin might look like this:
+
+```no-highlight
+plugin_name/
+  - plugin_name/
+    - templates/
+      - *.html
+    - __init__.py
+    - middleware.py
+    - navigation.py
+    - signals.py
+    - template_content.py
+    - urls.py
+    - views.py
+  - setup.py
+```
+
+The top level is the project root, which is typically synonymous with the git repository. A file named `setup.py` must exist at the top level to register the plugin within NetBox and to define meta data. You might also find miscellaneous other files within the project root, such as `.gitignore`.
+
+The second level directory houses the actual plugin code, arranged in a set of Python files. These are arbitrary, however the plugin _must_ include a `__init__.py` file which provides an AppConfig subclass.
+
+### Create setup.py
+
+The first step is to write our Python [setup script](https://docs.python.org/3.6/distutils/setupscript.html), which facilitates the installation of the plugin. This is standard practice for Python applications, with the only really noteworthy bit being the declared `entry_points`: The plugin must define an entry point for `netbox.plugin` pointing to the NetBoxPluginMeta class.
+
+```python
+from setuptools import setup, find_packages
+
+setup(
+    name='netbox-animal-sounds',
+    version='0.1',
+    description='Show animals and the sounds they make',
+    url='https://github.com/organization/animal-sounds',
+    author='Author Name',
+    author_email='author@example.com',
+    license='Apache 2.0',
+
+    install_requires=[],
+    packages=find_packages(exclude=['tests', 'tests.*']),
+    include_package_data=True,
+    entry_points={
+        'netbox.plugin': 'netbox_animal_sounds=netbox_animal_sounds:NetBoxPluginMeta'
+    }
+)
+
+```
+
+### Define an AppConfig
+
+

docs/plugins/index.md

@@ -0,0 +1,64 @@
+# Plugins
+
+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.
+
+Plugins are supported on NetBox v2.8 and later.
+
+## Capabilities
+
+The NetBox plugin architecture allows for the following:
+
+* **Add new data models.** A plugin can introduce one or more models to hold data. (A model is essentially a SQL table.)
+* **Add new URLs and views.** Plugins can register URLS under the `/plugins` root path to provide browsable views for users.
+* **Add content to existing model templates.** A template content class can be used to inject custom HTML content within the view of a core NetBox model. This content can appear in the left side, right side, or bottom of the page.
+* **Add navigation menu items.** Each plugin can register new links in the navigation menu. Each link may have a set of buttons for specific actions, similar to the built-in navigation items.
+* **Add custom middleware.** Custom Django middleware can be registered by each plugin.
+* **Declare configuration parameters.** Each plugin can define required, optional, and default configuration parameters within its unique namespace.
+* **Limit installation by NetBox version.** A plugin can specify a minimum and/or maximum NetBox version with which it is compatible.
+
+## Limitations
+
+Either by policy or by technical limitation, the interaction of plugins with NetBox core is restricted in certain ways. These include:
+
+* **Modify core models.** Plugins may not alter, remove, or override core NetBox models in any way. This rule is in place to ensure the integrity of the core data model.
+* **Register URLs outside the `/plugins` root.`** All plugin URLs are restricted to this path to prevent name/path collisions.
+* **Override core templates.** The only avenue available for injecting content into core templates is the provided
+* **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
+
+TODO
+
+### Enable Plugins
+
+In `configuration.py`, set the `PLUGINS_ENABLED` parameter to True (if not already set):
+
+```python
+PLUGINS_ENABLED = True
+```
+
+### 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'
+    }
+}
+```
+
+### Restart WSGI Service
+
+Restart the WSGI service to detect the new plugin:
+
+```no-highlight
+# sudo systemctl restart netbox
+```

mkdocs.yml

@@ -11,7 +11,6 @@ markdown_extensions:
     - admonition:
     - markdown_include.include:
         headingOffset: 1
-
 nav:
     - Introduction: 'index.md'
     - Installation:
@@ -53,6 +52,9 @@ nav:
         - Reports: 'additional-features/reports.md'
         - Tags: 'additional-features/tags.md'
         - Webhooks: 'additional-features/webhooks.md'
+    - Plugins:
+        - Using Plugins: 'plugins/index.md'
+        - Developing Plugins: 'plugins/development.md'
     - Administration:
         - Replicating NetBox: 'administration/replicating-netbox.md'
         - NetBox Shell: 'administration/netbox-shell.md'