add documentation about SASS and JS

1 files changed, 60 insertions, 0 deletions

diff --git a/doc/developer/js-css.rst b/doc/developer/js-css.rst
new file mode 100644
index 0000000..016dab1
--- /dev/null
+++ b/doc/developer/js-css.rst
@@ -0,0 +1,60 @@
+JavaScript & CSS
+================
+
+Like any web application, Fietsboek makes use of CSS and JavaScript. While
+Fietsboek is a Python application, and its dependencies are managed via
+Poetry_, it still uses npm_ to download and update the client-side JavaScript
+libraries.
+
+Furthermore, Fietsboek uses SASS_ to pre-compile the CSS files, and in the
+future will also use TypeScript_ to pre-compile the JavaScript files.
+Therefore, it is useful to know at least the basics of the
+``sass``/``tsc``/``npm`` utilities.
+
+In any case, all generated files are commited to the repository. As such, if
+you don't want to change the JavaScript/CSS files, you do not have to bother
+with any of that.
+
+.. warning::
+
+    If you do want to change JavaScript or CSS, always edit the source files.
+    Otherwise your changes will get overwritten the next time the
+    SASS/TypeScript compiler is run.
+
+.. _Poetry: https://python-poetry.org/
+.. _npm: https://www.npmjs.com/
+.. _SASS: https://sass-lang.com/
+.. _TypeScript: https://www.typescriptlang.org/
+
+Updating JavaScript libraries
+-----------------------------
+
+As mentioned, ``npm`` is used to manage the JavaScript libraries. You can check
+whether libraries are outdated and update them with the following commands::
+
+    npm outdated
+    npm update
+
+In addition, there is a ``justfile`` target that copies the assets from the
+:file:`node_modules` directory to the :file:`fietsboek/static/` directory::
+
+    just copy-npm-assets
+
+Compiling SASS
+--------------
+
+The SASS style files are located in :file:`asset-sources`. Do *not* edit the
+CSS files in :file:`fietsboek/static` directly, as those changes will get
+overwritten!
+
+The SASS compiler is installed via ``npm``, and a ``justfile`` target exists to
+compile the right SASS files::
+
+    npm install
+    just compile-sass
+
+Compiling TypeScript
+--------------------
+
+Fietsboek does not *yet* use TypeScript. The JavaScript file
+:file:`fietsboek/static/fietsboek.js` can be edited by hand.