Some small documentation tweaks (#119)

* Add favicon for docs

* Increase sidebar max tree depth, enable YAML syntax highlighting

* Add note about running rqworker alongside the runserver for testing purposes

* A few more minor docs corrections

* More updates for clarity

mkdocs.yml

@@ -7,7 +7,9 @@ python:
         - requirements: docs/requirements.txt
 theme:
     name: readthedocs
-    navigation_depth: 3
+    navigation_depth: 4
+    hljs_languages:
+        - yaml
 extra_css:
     - extra.css
 markdown_extensions:
@@ -19,12 +21,12 @@ markdown_extensions:
 nav:
     - Introduction: 'index.md'
     - Installation:
-        - Install Nautobot: 'installation/index.md'
-        - Deploy Nautobot: 'installation/nautobot.md'
-        - Configure Web Services: 'installation/wsgi.md'
-        - Configure HTTP Server: 'installation/http-server.md'
-        - Configure External Authentication (Optional): 'installation/external-authentication.md'
-    - Administration:
+        - Installing Prerequisites: 'installation/index.md'
+        - Installing Nautobot: 'installation/nautobot.md'
+        - Deploying Nautobot: 'installation/wsgi.md'
+        - Configuring an HTTP Server: 'installation/http-server.md'
+        - External Authentication (Optional): 'installation/external-authentication.md'
+    - Migration:
         - Migrating from NetBox: 'installation/migrating-from-netbox.md'
         - Upgrading Nautobot: 'installation/upgrading.md'
     - Configuration:

nautobot/docs/administration/nautobot-shell.md

@@ -175,7 +175,7 @@ To modify an existing object, we retrieve it, update the desired field(s), and c
 ```
 
 !!! warning
-   It is recommended to make use of the `validated_save()` convenience method which exists on all core models. While the Django `save()` method still exists, the `validated_save()` method saves the instance data but first enforces model validation logic. Simply calling `save()` on the model instance **does not** enforce validation automatically and may lead to bad data. See the development [best practices](../development/best-practices.md).
+    It is recommended to make use of the `validated_save()` convenience method which exists on all core models. While the Django `save()` method still exists, the `validated_save()` method saves the instance data but first enforces model validation logic. Simply calling `save()` on the model instance **does not** enforce validation automatically and may lead to bad data. See the development [best practices](../development/best-practices.md).
 
 !!! warning
     The Django ORM provides methods to create/edit many objects at once, namely `bulk_create()` and `update()`. These are best avoided in most cases as they bypass a model's built-in validation and can easily lead to database corruption if not used carefully.

nautobot/docs/administration/replicating-nautobot.md

@@ -34,7 +34,7 @@ psql -c 'create database nautobot'
 psql nautobot < nautobot.sql
 ```
 
-Keep in mind that PostgreSQL user accounts and permissions are not included with the dump: You will need to create those manually if you want to fully replicate the original database (see the [installation docs](../installation/#install-nautobot)). When setting up a development instance of Nautobot, it's strongly recommended to use different credentials anyway.
+Keep in mind that PostgreSQL user accounts and permissions are not included with the dump: You will need to create those manually if you want to fully replicate the original database (see the [installation docs](../../installation/#installing-nautobot-dependencies)). When setting up a development instance of Nautobot, it's strongly recommended to use different credentials anyway.
 
 ### Export the Database Schema
 

nautobot/docs/development/getting-started.md

@@ -131,8 +131,8 @@ The `devcontainer` will startup now. As a last step open the folder `/opt/nautob
 There are a few things you'll need:
 
 - A Linux system or environment
-- A PostgreSQL server, which can be installed locally [per the documentation](../../installation/#install-nautobot)
-- A Redis server, which can also be [installed locally](../../installation/#install-nautobot)
+- A PostgreSQL server, which can be installed locally [per the documentation](../../installation/#installing-nautobot-dependencies)
+- A Redis server, which can also be [installed locally](../../installation/#installing-nautobot-dependencies)
 - A supported version of Python
 - A recent version of [Poetry](https://python-poetry.org/docs/#installation)
 

nautobot/docs/installation/centos.md

@@ -1,4 +1,4 @@
-# CentOS/RHEL
+# Installing Nautobot Dependencies on CentOS/RHEL
 
 This installation guide assumes that you are running CentOS or RHEL version 8.2+ on your system.
 
@@ -123,4 +123,4 @@ PONG
 
 ## Deploy Nautobot
 
-Now that Nautobot dependencies are installed and configured, you're ready to [Deploy Nautobot](../nautobot)!
+Now that Nautobot dependencies are installed and configured, you're ready to [Install Nautobot](../nautobot)!

nautobot/docs/installation/http-server.md

@@ -1,7 +1,7 @@
-# Configure HTTP Server
+# Configuring an HTTP Server
 
 !!! warning
-    As of Nautobot v1.0.0b1 these instructions are in a pre-release state and will be evolving rapidly!
+    As of Nautobot v1.0.0b2 these instructions are in a pre-release state and will be evolving rapidly!
 
 This documentation provides example configurations for both [NGINX](https://www.nginx.com/resources/wiki/) and
 [Apache](https://httpd.apache.org/docs/current/), though any HTTP server which supports WSGI should be compatible.

nautobot/docs/installation/index.md

@@ -1,15 +1,15 @@
 # Installation
 
-This document will help you get Nautobot up and running.
+This set of documents will help you get Nautobot up and running.
 
 !!! warning
-    As of Nautobot v1.0.0b1 these instructions are still in a pre-release state. We are working to revise them for the recent changes.
+    As of Nautobot v1.0.0b2 these instructions are still in a pre-release state. We are working to revise them for the recent changes.
 
-## Dependencies
+## About Dependencies
 
 This section describes the system dependencies required for Nautobot. They can be all installed on a single system, or distributed across your environment. That will be up to you. Our install instructions assume a single system install, and that is good for most use cases. More advanced configurations are also possible, but are not covered here.
 
-The [installation instructions](#install-nautobot) below will guide you through a fresh installation.
+The [installation instructions](#installing-nautobot-dependencies) below will guide you through a fresh installation.
 
 ### Mandatory dependencies
 
@@ -59,27 +59,27 @@ For additional features:
 - [NAPALM support](../additional-features/napalm) for retrieving operational data from network devices
 - [Prometheus metrics](../additional-features/prometheus-metrics) for exporting application performance and telemetry data
 
-## Install Nautobot
+## Installing Nautobot Dependencies
 
 Nautobot was designed to be a cross-platform application that can run on nearly any system that is able to run the
 required dependencies. *Only the operating system platforms listed below are officially supported at this time*.
 
 Nautobot has been tested and confirmed to work on the following platforms. Detailed install and deployment instructions
 can be found by following the link to each.
 
-### Installing Nautobot on CentOS/RHEL
+### Installing Nautobot Dependencies on CentOS/RHEL
 
 Red Hat flavors of Linux including CentOS 8.2+ or Red Hat Enterprise Linux (RHEL) 8.2+ are supported. The same installation instructions can be used on either.
 
-- [Installing Nautobot on CentOS/RHEL](centos) 
+- [Installing Nautobot Dependencies on CentOS/RHEL](centos)
 
-### Installing Nautobot on Ubuntu
+### Installing Nautobot Dependencies on Ubuntu
 
 Ubuntu 20.04 or later is supported.
 
-- [Installing Nautobot on Ubuntu](ubuntu)
+- [Installing Nautobot Dependencies on Ubuntu](ubuntu)
 
-### Installing Nautobot on Other Systems
+### Installing on Other Systems
 
 Nautobot should work on any POSIX-compliant system including practically any flavor of Linux, BSD, or even macOS, but those are not *officially* supported at this time.
 

nautobot/docs/installation/nautobot.md

@@ -1,18 +1,19 @@
-# Deploy Nautobot
+# Installing Nautobot
 
 This section of the documentation discusses installing and configuring the Nautobot application itself.
 
-The instructions will guide you through the following actions:
+These instructions will guide you through the following actions:
 
 - Establish a Nautobot root directory for the application environment
 - Create a `nautobot` system account
 - Create a Python virtual environment (virtualenv)
 - Install Nautobot and all required Python packages
 - Run the database schema migrations
 - Aggregate static resource files on disk
+- Verify the installation using the development/test server
 
 !!! important
-    PostgreSQL and Redis must have been successfully installed before continuing with deployment steps. If you haven't done that yet, please visit the guide on [Installing Nautobot](../../installation/#install-nautobot)
+    PostgreSQL and Redis must have been successfully installed before continuing with deployment steps. If you haven't done that yet, please visit the guide on [Installing Nautobot Dependencies](../../installation/#installing-nautobot-dependencies)
 
 ## Choose your `NAUTOBOT_ROOT`
 
@@ -262,6 +263,9 @@ Next, connect to the name or IP of the server (as defined in `ALLOWED_HOSTS`) on
 !!! warning
     If the test service does not run, or you cannot reach the Nautobot home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected.
 
+!!! important
+    Certain Nautobot features (Git repository synchronization, webhooks, jobs, etc.) depend on the presence of Nautobot's background worker process, which is not automatically started by the `runserver` command. To start it for testing purposes, you can run `nautobot-server rqworker` separately. For production use, both Nautobot and the worker should be managed by systemd rather than started manually, as described in the next section of this documentation.
+
 Note that the initial user interface will be locked down for non-authenticated users.
 
 ![Nautobot UI as seen by a non-authenticated user](../media/installation/nautobot_ui_guest.png)
@@ -270,4 +274,4 @@ Try logging in using the superuser account we just created. Once authenticated,
 
 ![Nautobot UI as seen by an administrator](../media/installation/nautobot_ui_admin.png)
 
-Type `Ctrl-C` to stop the development server.
+Type `Ctrl-C` to stop the development server. Now you're ready to proceed to [starting Nautobot as a system service](../wsgi).

nautobot/docs/installation/ubuntu.md

@@ -1,4 +1,4 @@
-# Ubuntu
+# Installing Nautobot Dependencies on Ubuntu
 
 This installation guide assumes that you are running Ubuntu version 20.04 on your system.
 
@@ -76,4 +76,4 @@ PONG
 
 ## Deploy Nautobot
 
-Now that Nautobot dependencies are installed and configured, you're ready to [Deploy Nautobot](../nautobot)!
+Now that Nautobot dependencies are installed and configured, you're ready to [Install Nautobot](../nautobot)!

nautobot/docs/installation/wsgi.md

@@ -1,7 +1,7 @@
-# Configure Web Services
+# Deploying Nautobot: Web Service and Worker
 
 !!! warning
-    As of Nautobot v1.0.0b1 these instructions are in a pre-release state and will be evolving rapidly!
+    As of Nautobot v1.0.0b2 these instructions are in a pre-release state and will be evolving rapidly!
 
 Like most Django applications, Nautobot runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server.
 
@@ -157,4 +157,4 @@ You can use the command `systemctl status nautobot.service` to verify that the W
     If the Nautobot service fails to start, issue the command `journalctl -eu nautobot.service` to check for log messages that
     may indicate the problem.
 
-Once you've verified that the WSGI workers are up and running, move on to [HTTP server setup](../http-server).
+Once you've verified that the WSGI service and worker are up and running, move on to [HTTP server setup](../http-server).