From a39d6674a7c93726566089ba45380ba5080206e9 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Mon, 19 Jul 2021 13:29:14 -0400 Subject: [PATCH] Incorporate local documentation build in upgrade script --- .gitignore | 1 + base_requirements.txt | 8 ++++++++ docs/installation/3-netbox.md | 3 ++- docs/installation/upgrading.md | 2 +- docs/requirements.txt | 7 ++++++- mkdocs.yml | 1 + netbox/netbox/settings.py | 7 ++++--- requirements.txt | 2 ++ upgrade.sh | 5 +++++ 9 files changed, 30 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 66f4cb2ae..c9a3a3a55 100644 --- a/.gitignore +++ b/.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/* 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/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..47b10a284 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: 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/requirements.txt b/requirements.txt index 2acf122b7..31c42e142 100644 --- a/requirements.txt +++ b/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 diff --git a/upgrade.sh b/upgrade.sh index ae0c98634..c4d948e20 100755 --- a/upgrade.sh +++ b/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)..."