Incorporate local documentation build in upgrade script

.gitignore

@@ -2,6 +2,7 @@
 *.swp
 node_modules
 /netbox/project-static/.cache
+/netbox/project-static/docs/
 /netbox/netbox/configuration.py
 /netbox/netbox/ldap_config.py
 /netbox/reports/*

base_requirements.txt

@@ -74,6 +74,14 @@ Jinja2
 # https://github.com/Python-Markdown/markdown
 Markdown
 
+# File inclusion plugin for Python-Markdown
+# https://github.com/cmacmackin/markdown-include
+markdown-include
+
+# MkDocs Material theme (for documentation build)
+# https://github.com/squidfunk/mkdocs-material
+mkdocs-material
+
 # Library for manipulating IP prefixes and addresses
 # https://github.com/drkjam/netaddr
 netaddr

docs/installation/3-netbox.md

@@ -214,8 +214,9 @@ sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"
 Once NetBox has been configured, we're ready to proceed with the actual installation. We'll run the packaged upgrade script (`upgrade.sh`) to perform the following actions:
 
 * Create a Python virtual environment
-* Install all required Python packages
+* Installs all required Python packages
 * Run database schema migrations
+* Builds the documentation locally (for offline use)
 * Aggregate static resource files on disk
 
 ```no-highlight

docs/installation/upgrading.md

@@ -81,10 +81,10 @@ This script performs the following actions:
 * Installs all required Python packages (listed in `requirements.txt`)
 * Installs any additional packages from `local_requirements.txt`
 * Applies any database migrations that were included in the release
+* Builds the documentation locally (for offline use)
 * Collects all static files to be served by the HTTP service
 * Deletes stale content types from the database
 * Deletes all expired user sessions from the database
-* Clears all cached data to prevent conflicts with the new release
 
 !!! note
     If the upgrade script prompts a warning about unreflected database migrations, this indicates that some change has

docs/requirements.txt

@@ -1,2 +1,7 @@
+# File inclusion plugin for Python-Markdown
+# https://github.com/cmacmackin/markdown-include
+markdown-include
+
+# MkDocs Material theme (for documentation build)
+# https://github.com/squidfunk/mkdocs-material
 mkdocs-material
-git+https://github.com/cmacmackin/markdown-include.git

mkdocs.yml

@@ -1,4 +1,5 @@
 site_name: NetBox Documentation
+site_dir: netbox/project-static/docs
 site_url: https://netbox.readthedocs.io/
 repo_url: https://github.com/netbox-community/netbox
 python:

netbox/netbox/settings.py

@@ -379,10 +379,11 @@ X_FRAME_OPTIONS = 'SAMEORIGIN'
 
 # Static files (CSS, JavaScript, Images)
 STATIC_ROOT = BASE_DIR + '/static'
-STATIC_URL = '/{}static/'.format(BASE_PATH)
+STATIC_URL = f'/{BASE_PATH}static/'
 STATICFILES_DIRS = (
-    os.path.join(BASE_DIR, "project-static", "dist"),
+    os.path.join(BASE_DIR, 'project-static', 'dist'),
-    os.path.join(BASE_DIR, "project-static", "img"),
+    os.path.join(BASE_DIR, 'project-static', 'img'),
+    ('docs', os.path.join(BASE_DIR, 'project-static', 'docs')),  # Prefix with /docs
 )
 
 # Media

requirements.txt

@@ -17,6 +17,8 @@ graphene_django==2.15.0
 gunicorn==20.1.0
 Jinja2==3.0.1
 Markdown==3.3.4
+markdown-include==0.6.0
+mkdocs-material==7.1.11
 netaddr==0.8.0
 Pillow==8.3.1
 psycopg2-binary==2.9.1

upgrade.sh

@@ -82,6 +82,11 @@ COMMAND="python3 netbox/manage.py trace_paths --no-input"
 echo "Checking for missing cable paths ($COMMAND)..."
 eval $COMMAND || exit 1
 
+# Build the local documentation
+COMMAND="mkdocs build"
+echo "Building documentation ($COMMAND)..."
+eval $COMMAND || exit 1
+
 # Collect static files
 COMMAND="python3 netbox/manage.py collectstatic --no-input"
 echo "Collecting static files ($COMMAND)..."