diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 40c32ce3e..a8e62642e 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 66f4cb2ae..1ae9a10bb 100644 --- a/.gitignore +++ b/.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/* diff --git a/base_requirements.txt b/base_requirements.txt index 856439627..acd8d22c8 100644 --- a/base_requirements.txt +++ b/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 diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index 5a4021a01..589fb8c29 100644 --- a/docs/installation/3-netbox.md +++ b/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 diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index a238c9908..ba72225d4 100644 --- a/docs/installation/upgrading.md +++ b/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 diff --git a/docs/models/ipam/iprange.md b/docs/models/ipam/iprange.md index 9d64ed964..ab712e5b2 100644 --- a/docs/models/ipam/iprange.md +++ b/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 diff --git a/docs/release-notes/version-3.0.md b/docs/release-notes/version-3.0.md index 9ea90aecf..ffe06d844 100644 --- a/docs/release-notes/version-3.0.md +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 18b55d37b..c8726f8e6 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 031fab634..29c60caf2 100644 --- a/mkdocs.yml +++ b/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' diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index f3dc3af87..84209ada1 100644 --- a/netbox/netbox/settings.py +++ b/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 diff --git a/netbox/project-static/docs/.info b/netbox/project-static/docs/.info new file mode 100644 index 000000000..c0cdaa5e8 --- /dev/null +++ b/netbox/project-static/docs/.info @@ -0,0 +1 @@ +Build local for local documentation diff --git a/netbox/templates/base/layout.html b/netbox/templates/base/layout.html index 8de495a36..36eef2254 100644 --- a/netbox/templates/base/layout.html +++ b/netbox/templates/base/layout.html @@ -43,7 +43,7 @@