Corrections in documentation about nbshell

docs/administration/netbox-shell.md

@@ -1,6 +1,6 @@
 # The NetBox Python Shell
 
-NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command from a shell that has the netbox virtualenv activated:
+NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command with the appropriate Python virtual environment activated:
 
 ```
 ./manage.py nbshell
@@ -105,6 +105,8 @@ This approach can span multiple levels of relations. For example, the following
 >>> IPAddress.objects.filter(interface__device__site__region__slug="north-america")
 ```
 
+The `get()` method can be used in place of the `filter()` method if we expect this query to return only one object. This method will yield the actual object resulting from the query, instead of a QuerySet. If the query returns more than one result, it will raise an exception.
+
 !!! note
     While the above query is functional, it's not very efficient. There are ways to optimize such requests, however they are out of scope for this document. For more information, see the [Django queryset method reference](https://docs.djangoproject.com/en/stable/ref/models/querysets/) documentation.
 
@@ -143,39 +145,7 @@ To return the inverse of a filtered queryset, use `exclude()` instead of `filter
 346
 ```
 
-If the query returns only one object, the get() method can be used. This method will yield the actual object resulting from the query, instead of a QuerySet. For this to work, the query must return only one object. The syntax is identical to the filter and exclude methods. For example, we can get a device from it's asset tag:
-
-```
->>>
->>> Device.objects.get(asset_tag="100079912515")
-<Device: AP994003 (100079912515)>
->>>
-```
-
-If the query returns more than one object, a MultipleObjectsReturned exception will be thrown:
-
-```
->>> Device.objects.get(role_id=13)
-Traceback (most recent call last):
-  File "<console>", line 1, in <module>
-  File "/srv/netbox/venv/lib/python3.10/site-packages/django/db/models/manager.py", line 87, in manager_method
-    return getattr(self.get_queryset(), name)(*args, **kwargs)
-  File "/srv/netbox/venv/lib/python3.10/site-packages/django/db/models/query.py", line 640, in get
-    raise self.model.MultipleObjectsReturned(
-dcim.models.devices.Device.MultipleObjectsReturned: get() returned more than one Device -- it returned more than 20!
->>>
-```
-
-Queries can all also be executed from a particular object instead of from the model itself. For instance, to get all circuits that are assigned to one site, it is easier to filter from the site itself, instead of using the "Circuit" model and building the query from there. This is particularly useful for configuration templates and export templates, since it allows to query other database objects that are related to the object that we're rendering the template for.
-
-```
->>> site.circuit_terminations.all()
-<RestrictedQuerySet [<CircuitTermination: 20899518: Termination A>, <CircuitTermination: DT00018356: Termination A>]>
->>>
-```
-
-The same methods (all, filter, exclude, get...) can be used in this kind of queries.
-
+Queries can all also be executed from a particular object instead of from the model itself. For instance, to get all circuits that are assigned to one site, it is easier to filter from the site itself, instead of using the "Circuit" model and building the query from there. This is particularly useful for configuration templates and export templates, since it allows to query other database objects that are related to the object that we're rendering the template for. The same methods (all, filter, exclude, get...) can be used in this kind of queries.
 
 !!! info
     The examples above are intended only to provide a cursory introduction to queryset filtering. For an exhaustive list of the available filters, please consult the [Django queryset API documentation](https://docs.djangoproject.com/en/stable/ref/models/querysets/).

docs/customization/custom-scripts.md

@@ -56,13 +56,11 @@ class AnotherCustomScript(Script):
 script_order = (MyCustomScript, AnotherCustomScript)
 ```
 
-### The run() method
+### The `run()` Method
 
-The run() method is the entrypoint for the script, and it runs in the context of Netbox's own execution environment. This means from here, everything inside Netbox itself is accesible. The [Netbox Shell](../administration/netbox-shell.md) is a good resource to keep in hand, since it allows to see the objects in Netbox in the same way the run() method of the script does.
+The `run()` method is the entrypoint for the script, and it runs in the context of NetBox's own execution environment. This means from here, everything inside NetBox itself is accesible. The [NetBox Shell](../administration/netbox-shell.md) is a good resource to keep in hand, since it allows to see the objects in NetBox in the same way the script does.
 
-The run() method can itself call other methods that are in the same module but outside the "MyCustomScript" class, and if there are several scripts in the same module (this is, in the same Python file), both scripts can reuse the same auxiliary methods, keeping the code cleaner. For this reason, it is encouraged to keep similar scripts in the same module.
-
-The run() method can return a string, and this will be displayed in a text box in the web interface after the script finishes. This is useful, for instance, for returning a piece of configuration or information that you want the user to be able to easily copy and paste somewhere else.
+The `run()` method can itself call other methods that are in the same module but outside the "MyCustomScript" class, and if there are several scripts in the same module (this is, in the same Python file), both scripts can reuse the same auxiliary methods, keeping the code cleaner. For this reason, it is encouraged to keep similar scripts in the same module. Script can return a string, which will be displayed in a text box in the web interface after the script finishes. This is useful, for instance, for returning a piece of configuration or information that you want the user to be able to easily copy and paste somewhere else.
 
 
 ## Module Attributes

docs/customization/export-templates.md

@@ -32,7 +32,8 @@ If you need to use the config context data in an export template, you'll should
 {% endfor %}
 ```
 
-To see all the attributes of a given object, you can use the [Netbox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within a Jinja template. Using queries from one object to another, one can navigate pretty much the entire Netbox object model. For instance, from an export template for sites, one can get the devices that are in that site, the circuits that are connected to those devices, the providers that serve those circuits... etc, so an export template is not limited to just the model that it's being called from. In fact, the same result can be achieved in different ways, depending on which model you start from.
+!!! info
+    To see all the attributes of a given object, you can use the [NetBox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within a Jinja template.
 
 The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.)
 

docs/customization/reports.md

@@ -29,7 +29,7 @@ class DeviceIPsReport(Report):
     description = "Check that every device has a primary IP address assigned"
 ```
 
-Within each report class, we'll create a number of test methods to execute our report's logic. The method's name must start with "test_" and it takes no arguments.
+Within each report class, we'll create a number of test methods to execute our report's logic. The name of each method must begin with `test_` and the method must accept no arguments.
 
 In DeviceConnectionsReport, for instance, we want to ensure that every live device has a console connection, an out-of-band management connection, and two power connections.
 
@@ -84,7 +84,8 @@ class DeviceConnectionsReport(Report):
 
 As you can see, reports are completely customizable. Validation logic can be as simple or as complex as needed. Also note that the `description` attribute support markdown syntax. It will be rendered in the report list page.
 
-In the same way scripts do, reports run from within Netbox's own environment and can access the objects inside Netbox directly. The [Netbox Shell](../administration/netbox-shell.md) is a good resource to keep in hand, since it allows to see the objects in Netbox in the same way the test methods of a report do.
+!!! info
+    In the same way scripts do, reports run from within NetBox's own environment and can access the objects inside NetBox directly. The [NetBox Shell](../administration/netbox-shell.md) is a good resource to keep in hand, since it allows to see the objects in NetBox in the same way the reports and scripts do.
 
 !!! warning
     Reports should never alter data: If you find yourself using the `create()`, `save()`, `update()`, or `delete()` methods on objects within reports, stop and re-evaluate what you're trying to accomplish. Note that there are no safeguards against the accidental alteration or destruction of data.

docs/features/configuration-rendering.md

@@ -35,7 +35,8 @@ Configuration templates are written in the [Jinja2 templating language](https://
 {% endblock %}
 ```
 
-To see all the attributes of a given object, you can use the [Netbox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within the configuration template. Also, other objects, for instance, a device's interfaces or connected circuits can be accessed from the template itself, so the rendered configuration may include information not only about the device itself, but also related objects like IP addresses or circuits.
+!!! info
+    To see all the attributes of a given object, you can use the [NetBox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within the configuration template.
 
 When rendered for a specific NetBox device, the template's `device` variable will be populated with the device instance, and `ntp_servers` will be pulled from the device's available context data. The resulting output will be a valid configuration segment that can be applied directly to a compatible network device.