Closes #6328: Local docs build (#6769)

* Incorporate local documentation build in upgrade script

* Add docs build to CI

* Include docs build path in revision control

* Update footer dcos link

* Changelog for #6328

* Clean up errant links

.github/workflows/ci.yml

@@ -40,6 +40,9 @@ jobs:
         pip install pycodestyle coverage
         ln -s configuration.testing.py netbox/netbox/configuration.py
 
+    - name: Build documentation
+      run: mkdocs build
+
     - name: Collect static files
       run: python netbox/manage.py collectstatic --no-input
 

.gitignore

@@ -2,6 +2,8 @@
 *.swp
 node_modules
 /netbox/project-static/.cache
+/netbox/project-static/docs/*
+!/netbox/project-static/docs/.info
 /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/models/ipam/iprange.md

@@ -2,7 +2,7 @@
 
 This model represents an arbitrary range of individual IPv4 or IPv6 addresses, inclusive of its starting and ending addresses. For instance, the range 192.0.2.10 to 192.0.2.20 has eleven members. (The total member count is available as the `size` property on an IPRange instance.) Like prefixes and IP addresses, each IP range may optionally be assigned to a VRF and/or tenant.
 
-IP also ranges share the same [functional roles](role.md) as prefixes and VLANs, although the assignment of a role is optional. Each IP range must be assigned an operational status, which is one of the following:
+IP also ranges share the same functional roles as prefixes and VLANs, although the assignment of a role is optional. Each IP range must be assigned an operational status, which is one of the following:
 
 * Active - Provisioned and in use
 * Reserved - Designated for future use

docs/release-notes/version-3.0.md

@@ -181,6 +181,7 @@ Note that NetBox's `rqworker` process will _not_ service custom queues by defaul
 * [#5532](https://github.com/netbox-community/netbox/issues/5532) - Drop support for Python 3.6
 * [#5994](https://github.com/netbox-community/netbox/issues/5994) - Drop support for `display_field` argument on ObjectVar
 * [#6068](https://github.com/netbox-community/netbox/issues/6068) - Drop support for legacy static CSV export
+* [#6328](https://github.com/netbox-community/netbox/issues/6328) - Build and serve documentation locally
 * [#6338](https://github.com/netbox-community/netbox/issues/6338) - Decimal fields are no longer coerced to strings in REST API
 * [#6639](https://github.com/netbox-community/netbox/issues/6639) - Drop support for queryset caching (django-cacheops)
 * [#6713](https://github.com/netbox-community/netbox/issues/6713) - Checking for new releases is now done as part of the housekeeping routine

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:
@@ -67,7 +68,6 @@ nav:
         - Custom Scripts: 'customization/custom-scripts.md'
         - Reports: 'customization/reports.md'
     - Additional Features:
-        - Caching: 'additional-features/caching.md'
         - Change Logging: 'additional-features/change-logging.md'
         - Context Data: 'models/extras/configcontext.md'
         - Journaling: 'additional-features/journaling.md'

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", "img"),
+    os.path.join(BASE_DIR, 'project-static', 'dist'),
+    os.path.join(BASE_DIR, 'project-static', 'img'),
+    ('docs', os.path.join(BASE_DIR, 'project-static', 'docs')),  # Prefix with /docs
 )
 
 # Media

netbox/project-static/docs/.info

@@ -0,0 +1 @@
+Build local for local documentation

netbox/templates/base/layout.html

@@ -43,7 +43,7 @@
           <nav class="nav">
 
             {# Documentation #}
-            <a type="button" class="nav-link" href="https://netbox.readthedocs.io/" target="_blank">
+            <a type="button" class="nav-link" href="{% static 'docs/' %}" target="_blank">
               <i title="Docs" class="mdi mdi-book-open-variant text-primary" data-bs-placement="top" data-bs-toggle="tooltip"></i>
             </a>
 

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)..."