diff --git a/doc/hacking/hacking.rst b/doc/hacking/hacking.rst index b93d84c328..69798f2c91 100644 --- a/doc/hacking/hacking.rst +++ b/doc/hacking/hacking.rst @@ -156,6 +156,7 @@ Directory Description processes. :file:`python/` Python source code. :file:`python/nav/etc/` Example/initial configuration files. +:file:`python/nav/web/sass/` SCSS stylesheets. :file:`python/nav/web/static/` Static media such as CSS stylesheets, images and JavaScript to be served by a webserver. :file:`python/nav/web/templates/` Main/global Django HTML templates. More be located in individual @@ -283,6 +284,24 @@ developing, something browsers love to do! See `config-urlArgs documentation for details. :file:`require_config.dev.js` is listed in the repository :file:`.gitignore` file. +CSS +--- + +NAV uses Sass for styling. If you want to modify the styling, +you can do so by editing the SCSS files in the :file:`python/nav/web/static/scss` +directory. To build the CSS assets, you will need to have Node.js +and npm installed. Once you have these installed, you can run +the following command to build the CSS files:: + + npm install + npm run build:sass + +This will build the CSS assets and place them in the :file:`python/nav/web/static/css` +directory. If you want to watch for changes in the SCSS files and rebuild the +CSS assets automatically, you can run the following command instead:: + + npm run watch:sass + Database diff --git a/doc/hacking/using-docker.rst b/doc/hacking/using-docker.rst index 38bdeb03bc..c6b78958b4 100644 --- a/doc/hacking/using-docker.rst +++ b/doc/hacking/using-docker.rst @@ -187,9 +187,10 @@ nav starts. sass-watcher - This is a process that monitors the :file:`python/nav/web/sass/` subdirectory - for changes, and re-runs ``python setup.py build_sass`` (i.e. rebuilding all - the SASS-based stylesheets) on changes. + This is a process that runs ``npm run watch:sass`` command to monitor and + rebuild all the SASS-based stylesheets whenever changes occur + in the :file:`python/nav/web/sass/` subdirectory. The command continuously + monitors the files and does not exit by itself. The individual logs of these program are typically found inside the ``nav`` container in the :file:`/var/log/supervisor/` directory. The NAV process logs diff --git a/doc/howto/generic-install-from-source.rst b/doc/howto/generic-install-from-source.rst index d3443816fd..9440358fc3 100644 --- a/doc/howto/generic-install-from-source.rst +++ b/doc/howto/generic-install-from-source.rst @@ -5,6 +5,8 @@ This is a generic guide to installing NAV from source code on a \*NIX flavored operating system. The specifics of how to install NAV's dependencies, such as :xref:`PostgreSQL` or :xref:`Graphite` will be entirely up to you and your choice of OS. +Note that building NAV from source will also require Node.js and npm to be installed +in order to manage frontend assets. Dependencies @@ -21,6 +23,11 @@ To build NAV, you need at least the following: * Python >= 3.9.0 * Sphinx >= 1.0 (for building this documentation) +Additionally to build frontend assets (like CSS and JS), you will need: + + * Node.js >= 14.0 + * npm >= 6.0 + Runtime requirements -------------------- @@ -73,6 +80,16 @@ default. Installing NAV ============== +First you need to build the static assets. To do this, you will need to have +Node.js and npm installed. Once you have these installed, you can run +the following command to build the CSS assets:: + + npm install + npm run build:sass + +This will build the CSS assets and place them in the :file:`python/nav/web/static/css` +directory. + To build and install NAV and all its Python dependencies:: pip install -r requirements.txt -c constraints.txt . diff --git a/doc/intro/install.rst b/doc/intro/install.rst index 8cbf854adb..635c2c4120 100644 --- a/doc/intro/install.rst +++ b/doc/intro/install.rst @@ -7,7 +7,8 @@ There are two main options for installing NAV: Either from source code, or from a pre-packaged version. Some of these options will require manually installing and/or configuring 3rd party software that NAV depends on, mainly :xref:`PostgreSQL` -and :xref:`Graphite`. +and :xref:`Graphite`. Building NAV from source code will also require Node.js +and npm to be installed. Installing a pre-packaged version of NAV @@ -96,4 +97,3 @@ For you, we provide two guides: `. 2. :doc:`A step-by-step, detailed guide on installing NAV from source on a Debian GNU/Linux operating system `. -