Suggestions to improve the plugin tutorial

tutorial/step01-initial-setup.md

@@ -16,7 +16,7 @@ Be sure to enable debugging in your NetBox configuration by setting `DEBUG = Tru
 
 ### Clone the git Repository
 
-Next, we'll clone the demo git repository from GitHub. First, `cd` into your preferred location (your home directory is probably fine), then clone the repo with `git clone`. We're checking out the `init` branch, which will provide us with an empty workspace to start.
+Next, we'll clone the demo git repository from GitHub. First, `cd` into your preferred location (your home directory is probably fine), then clone the repo with `git clone`. We're checking out the `step00-empty` branch, which will provide us with an empty workspace to start.
 
 ```bash
 $ git clone --branch step00-empty https://github.com/netbox-community/netbox-plugin-demo
@@ -34,7 +34,10 @@ Unpacking objects: 100% (58/58), done.
 
 ### Create `__init__.py`
 
-The `PluginConfig` class holds all the information needs to know about our plugin to install it. First, we'll create a subdirectory to hold our plugin's Python code, as well as an `__init__.py` file to hold the `PluginConfig` definition.
+Our plugin is for managing access lists in NetBox, so we'll give it an appropriate name, such as `netbox_access_lists`.
+
+First, we'll create a subdirectory to hold our plugin's Python code, as well as an `__init__.py` file to hold the `PluginConfig` definition.
+The `PluginConfig` class holds all the information Netbox needs to know about our plugin to install it.
 
 ```bash
 $ mkdir netbox_access_lists
@@ -145,7 +148,7 @@ Save the file and run the NetBox development server (if not already running):
 $ python netbox/manage.py runserver
 ```
 
-You should see the development server start successfully. Open NetBox in a new browser window, log in as a superuser, and navigate to the admin UI. Under **System > Installed Plugins** you should see our plugin listed.
+You should see the development server start successfully. Open NetBox in a new browser window, log in as a superuser, and navigate to the admin UI. Under **Admin > System > Plugins** you should see our plugin listed.
 
 ![Django admin UI: Plugins list](/images/step01-django-admin-plugins.png)
 
@@ -158,4 +161,3 @@ This completes our initial setup. Now, onto the fun stuff!
 [Step 2: Models](/tutorial/step02-models.md) :arrow_right:
 
 </div>
-

tutorial/step02-models.md

@@ -103,7 +103,7 @@ The protocol field is next. This will store the name of a protocol such as TCP o
     )
 ```
 
-Next we need to define a source prefix. We're going to use a foreign key field to reference an instance of NetBox's `Prefix` model within its `ipam` app. Instead of importing the model class, we can instead reference it by name. And because we want this to be an _optional_ field, we'll also set `blank=True` and `null=True`.
+Next we need to define a source prefix. We're going to use a foreign key field to reference an instance of NetBox's [`Prefix` model](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/prefix/) within its `ipam` app. Instead of importing the model class, we can instead reference it by name. And because we want this to be an _optional_ field, we'll also set `blank=True` and `null=True`.
 
 ```python
     source_prefix = models.ForeignKey(
@@ -119,7 +119,7 @@ Next we need to define a source prefix. We're going to use a foreign key field t
 
 Notice above that we've defined `related_name='+'`. This tells Django not to create a reverse relationship from the `Prefix` model to the `AccessListRule` model, because it wouldn't be very useful.
 
-We also need to add a field for the source port number(s). We could use an integer field for this, however that would limit us to defining a single source port per rule. Instead, we can add an `ArrayField` to store a list of `PositiveIntegerField` values. Like `source_prefix`, this will also be an optional field, so we add `blank=True` and `null=True` as well.
+We also need to add a field for the source port number(s). We could use an integer field for this, however that would limit us to defining a single source port per rule. Instead, we can add an [`ArrayField`](https://docs.djangoproject.com/en/stable/ref/contrib/postgres/fields/#arrayfield) to store a list of `PositiveIntegerField` values. Like `source_prefix`, this will also be an optional field, so we add `blank=True` and `null=True` as well.
 
 ```python
     source_ports = ArrayField(
@@ -181,7 +181,7 @@ Looking back at our models, we see a few fields that would benefit from having p
 * Deny
 * Reject
 
-We can define a `ChoiceSet` to store these pre-defined values for the user, to avoid the hassle of manually typing the name of the desired action each time. Back at the top of `models.py`, import NetBox's `ChoiceSet` class:
+We can define a [`ChoiceSet`](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/models/#choice-sets) to store these pre-defined values for the user, to avoid the hassle of manually typing the name of the desired action each time. Back at the top of `models.py`, import NetBox's `ChoiceSet` class:
 
 ```python
 from utilities.choices import ChoiceSet
@@ -204,9 +204,9 @@ The `CHOICES` attribute must be an iterable of two- or three-value tuples, each
 
 * The raw value to be stored in the database
 * A human-friendly string for display
-* A color for display in the UI (optional, see [available colors](https://docs.netbox.dev/en/stable/configuration/data-validation/#field_choices))
+* A color for display in the UI (optional, see [available colors](https://netboxlabs.com/docs/netbox/en/stable/configuration/data-validation/#field_choices))
 
-Additionally, we've added a `key` attribute: This will allow the NetBox administrator to replace or extend the plugin's default choices via NetBox's [`FIELD_CHOICES`](https://netbox.readthedocs.io/en/stable/configuration/optional-settings/#field_choices) configuration parameter.
+Additionally, we've added a `key` attribute: This will allow the NetBox administrator to replace or extend the plugin's default choices via NetBox's [`FIELD_CHOICES`](https://netboxlabs.com/docs/netbox/en/stable/configuration/data-validation/#field_choices) configuration parameter.
 
 Now, we can reference this as the set of valid choices on the `default_action` and `action` model fields by passing it as the `choices` keyword argument.
 
@@ -274,7 +274,7 @@ class AccessListRule(NetBoxModel):
 
 ## Create Schema Migrations
 
-Now that we have our models defined, we need to generate a schema for the PostgreSQL database. While it's possible to create the tables and constraints by hand, it's _much_ easier to employ Django's [migrations feature](https://docs.djangoproject.com/en/4.0/topics/migrations/). This will inspect our model classes and generate the necessary migration files automatically. This is a two-step process: First we generate the migration file with the `makemigrations` management command, then we run `migrate` to apply it to the live database.
+Now that we have our models defined, we need to generate a schema for the PostgreSQL database. While it's possible to create the tables and constraints by hand, it's _much_ easier to employ Django's [migrations feature](https://docs.djangoproject.com/en/stable/topics/migrations/). This will inspect our model classes and generate the necessary migration files automatically. This is a two-step process: First we generate the migration file with the `makemigrations` management command, then we run `migrate` to apply it to the live database.
 
 :warning: **Warning:** Before continuing, check that you've set `DEVELOPER=True` in NetBox's `configuration.py` file. This is necessary to disable a safeguard intended to prevent people from creating new migrations mistakenly.
 

tutorial/step03-tables.md

@@ -15,7 +15,7 @@ $ cd netbox_access_lists/
 $ edit tables.py
 ```
 
-At the top of this file, import the `django-tables2` library. This will provide the column classes for fields we wish to customize. We'll also import NetBox's `NetBoxTable` class, which will serve as the base class for our tables, and `ChoiceFieldColumn`. Finally we import our plugin's models from `models.py`.
+At the top of this file, import the `django-tables2` library. This will provide the column classes for fields we wish to customize. We'll also import NetBox's [`NetBoxTable`](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/tables/#netboxtable) class, which will serve as the base class for our tables, and `ChoiceFieldColumn`. Finally we import our plugin's models from `models.py`.
 
 ```python
 import django_tables2 as tables
@@ -72,6 +72,10 @@ class AccessListTable(NetBoxTable):
         default_columns = ('name', 'rule_count', 'default_action')
 ```
 
+Once our plugin is finished, the table will look like this:
+
+![Access lists table](../images/step05-accesslist-list.png)
+
 ### AccessListRuleTable
 
 We'll also create a table for our `AccessListRule` model using the same approach as above. Start by linkifying the `access_list` and `index` columns. The former will link to the parent access list, and the latter will link to the individual rule. We also want to declare `protocol` and `action` as `ChoiceFieldColumn` instances.
@@ -106,4 +110,3 @@ This should be all we need to list these objects in the UI. Next, we'll define s
 :arrow_left: [Step 2: Models](/tutorial/step02-models.md) | [Step 4: Forms](/tutorial/step04-forms.md) :arrow_right:
 
 </div>
-

tutorial/step04-forms.md

@@ -13,7 +13,7 @@ $ cd netbox_access_lists/
 $ edit forms.py
 ```
 
-At the top of the file, we'll import NetBox's `NetBoxModelForm` class, which will serve as the base class for our forms. We'll also import our plugin's models.
+At the top of the file, we'll import NetBox's [`NetBoxModelForm`](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/forms/#netboxmodelform) class, which will serve as the base class for our forms. We'll also import our plugin's models.
 
 ```python
 from netbox.forms import NetBoxModelForm
@@ -32,7 +32,7 @@ class AccessListForm(NetBoxModelForm):
         fields = ('name', 'default_action', 'comments', 'tags')
 ```
 
-This alone is sufficient for our first model, but we can make one tweak: Instead of the default field that Django will generate for the `comments` model field, we can use NetBox's purpose-built `CommentField` class. (This handles some largely cosmetic details like setting a `help_text` and adjusting the field's layout.) To do this, simply import the `CommentField` class and override the form field:
+This alone is sufficient for our first model, but we can make one tweak: Instead of the default field that Django will generate for the `comments` model field, we can use NetBox's purpose-built [`CommentField`](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/forms/#utilities.forms.fields.fields.CommentField) class. (This handles some largely cosmetic details like setting a `help_text` and adjusting the field's layout.) To do this, simply import the `CommentField` class and override the form field:
 
 ```python
 from utilities.forms.fields import CommentField
@@ -45,6 +45,10 @@ class AccessListForm(NetBoxModelForm):
         fields = ('name', 'default_action', 'comments', 'tags')
 ```
 
+Once our plugin is finished, the form will look like this:
+
+![Access lists form](../images/step05-accesslist-form.png)
+
 ### AccessListRuleForm
 
 We'll create a form for `AccessListRule` following the same pattern.
@@ -62,7 +66,7 @@ class AccessListRuleForm(NetBoxModelForm):
 
 By default, Django will create a "static" foreign key field for related objects. This renders as a dropdown list that's pre-populated with _all_ available objects. As you can imagine, in a NetBox instance with many thousands of objects this can get rather unwieldy.
 
-To avoid this, NetBox provides the `DynamicModelChoiceField` class. This renders foreign key fields using a special dynamic widget backed by NetBox's REST API. This avoids the overhead imposed by the static field, and allows the user to conveniently search for the desired object.
+To avoid this, NetBox provides the [`DynamicModelChoiceField`](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/forms/#dynamic-object-fields) class. This renders foreign key fields using a special dynamic widget backed by NetBox's REST API. This avoids the overhead imposed by the static field, and allows the user to conveniently search for the desired object.
 
 :green_circle: **Tip:** The `DynamicModelMultipleChoiceField` class is also available for many-to-many fields, which support the assignment of multiple objects.
 
@@ -97,4 +101,3 @@ With our models, tables, and forms all in place, next we'll create some views to
 :arrow_left: [Step 3: Tables](/tutorial/step03-tables.md) | [Step 5: Views](/tutorial/step05-views.md) :arrow_right:
 
 </div>
-

tutorial/step05-views.md

@@ -2,7 +2,7 @@
 
 Views are responsible for the business logic of your application. Generally, this means processing incoming requests, performing some action(s), and returning a response to the client. Each view typically has a URL associated with it, and can handle one or more types of HTTP requests (i.e. `GET` and/or `POST` requests).
 
-Django provides a set of [generic view classes](https://docs.djangoproject.com/en/4.0/topics/class-based-views/generic-display/) which handle much of the boilerplate code needed to process requests. NetBox likewise provides a set of view classes to simplify the creation of views for creating, editing, deleting, and viewing objects. They also introduce support for NetBox-specific features such as custom fields and change logging.
+Django provides a set of [generic view classes](https://docs.djangoproject.com/en/stable/topics/class-based-views/generic-display/) which handle much of the boilerplate code needed to process requests. NetBox likewise provides a set of view classes to simplify the creation of views for creating, editing, deleting, and viewing objects. They also introduce support for NetBox-specific features such as custom fields and change logging.
 
 In this step, we'll create a set of views for each of our plugin's models.
 
@@ -17,7 +17,7 @@ $ cd netbox_access_lists/
 $ edit views.py
 ```
 
-We'll need to import our plugin's `models`, `tables`, and `forms` modules: This is where everything we've built so far really comes together! We also need to import NetBox's generic views module, as it provides the base classes for our views.
+We'll need to import our plugin's `models`, `tables`, and `forms` modules: This is where everything we've built so far really comes together! We also need to import [NetBox's generic views](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/views/#view-classes) module, as it provides the base classes for our views.
 
 ```python
 from netbox.views import generic
@@ -56,7 +56,7 @@ class AccessListListView(generic.ObjectListView):
 
 :green_circle: **Tip:** It occurs to the author that having chosen a model name that ends with "List" might be a bit confusing here. Just remember that `AccessListView` is the _detail_ (single object) view, and `AccessListListView` is the _list_ (multiple objects) view.
 
-Before we move on to the next view, do you remember the extra column we added to `AccessListTable` in step three? That column expects to find a count of rules assigned for each access list in the queryset, named `rule_count`. Let's add this to our queryset now. We can employ Django's `Count()` function to extend the SQL query and annotate the count of associated rules. (Don't forget to add the import statement up top.)
+Before we move on to the next view, do you remember the extra column we added to `AccessListTable` in step three? That column expects to find a count of rules assigned for each access list in the queryset, named `rule_count`. Let's add this to our queryset now. We can employ Django's [`Count()`](https://docs.djangoproject.com/en/stable/ref/models/querysets/#aggregation-functions) function to extend the SQL query and annotate the count of associated rules. (Don't forget to add the import statement up top.)
 
 ```python
 from django.db.models import Count
@@ -233,13 +233,16 @@ class AccessListRule(NetBoxModel):
 
 Now for the moment of truth: Has all our work thus far yielded functional UI views? Check that the development server is running, then open a browser and navigate to <http://localhost:8000/plugins/access-lists/access-lists/>. You should see the access list list view and (if you followed in step two) a single access list named MyACL1.
 
+The first `access-lists` in the URL is the `base_url` we defined in `__init__.py`.
+The second is the path we defined in `urls.py`.
+
 :blue_square: **Note:** This guide assumes that you're running the Django development server locally on port 8000. If your setup is different, you'll need to adjust the link above accordingly.
 
 ![Access lists list view](/images/step05-accesslist-list.png)
 
 We see that our table has successfully render the `name`, `rule_count`, and `default_action` columns that we defined in step three, and the `rule_count` column shows two rules assigned as expected.
 
-If we click the "Add" button at top right, we'll be taken to the access list creation form. (Creating a new access list won'r work yet, but the form should render as seen below.)
+If we click the "Add" button at top right, we'll be taken to the access list creation form. (Creating a new access list won't work yet, but the form should render as seen below.)
 
 ![Access list creation form](/images/step05-accesslist-form.png)
 

tutorial/step07-navigation.md

@@ -13,7 +13,7 @@ $ cd netbox_access_lists/
 $ edit navigation.py
 ```
 
-We'll need to import the `PluginMenuItem` class provided by NetBox to add new menu items; do this at the top of the file.
+We'll need to import the [`PluginMenuItem`](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/navigation/#menu-items) class provided by NetBox to add new menu items; do this at the top of the file.
 
 ```python
 from extras.plugins import PluginMenuItem
@@ -55,19 +55,17 @@ That's much more convenient!
 
 ### Adding Menu Buttons
 
-While we're at it, we can add direct links to the "add" views for access lists and rules as buttons. We'll need to import two additional classes at the top of `navigation.py`: `PluginMenuButton` and `ButtonColorChoices`.
+While we're at it, we can add direct links to the "add" views for access lists and rules as buttons. We'll need to import one additional class at the top of `navigation.py`: `PluginMenuButton`.
 
 ```python
 from extras.plugins import PluginMenuButton, PluginMenuItem
-from utilities.choices import ButtonColorChoices
 ```
 
 `PluginMenuButton` is used similarly to `PluginMenuItem`: Instantiate it with the necessary keyword arguments to effect a menu button. These arguments are:
 
 * `link` - The name of the URL path to which the button links
 * `title` - The text displayed when the user hovers over the button
 * `icon_class` - CSS class name(s) indicating the icon to display
-* `color` - The button's color (choices are provided by `ButtonColorChoices`)
 
 Create these instances in `navigation.py` _above_ `menu_items`. Because each menu item expects to receive an iterable of button instances, we'll create each of these inside a list.
 
@@ -77,7 +75,6 @@ accesslist_buttons = [
         link='plugins:netbox_access_lists:accesslist_add',
         title='Add',
         icon_class='mdi mdi-plus-thick',
-        color=ButtonColorChoices.GREEN
     )
 ]
 
@@ -86,7 +83,6 @@ accesslistrule_buttons = [
         link='plugins:netbox_access_lists:accesslistrule_add',
         title='Add',
         icon_class='mdi mdi-plus-thick',
-        color=ButtonColorChoices.GREEN
     )
 ]
 ```
@@ -117,4 +113,3 @@ Now we should see green "add" buttons appear next to our menu links.
 :arrow_left: [Step 6: Templates](/tutorial/step06-templates.md) | [Step 8: Filter Sets](/tutorial/step08-filter-sets.md) :arrow_right:
 
 </div>
-