From 87ac18615f74b81955b07ff526f56f1ed7843646 Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Wed, 22 Mar 2023 21:11:24 +0100
Subject: add documentation about SASS and JS

---
 doc/developer.rst        |  1 +
 doc/developer/js-css.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 doc/developer/js-css.rst

(limited to 'doc')

diff --git a/doc/developer.rst b/doc/developer.rst
index f6546ab..8b41c60 100644
--- a/doc/developer.rst
+++ b/doc/developer.rst
@@ -7,6 +7,7 @@ Developer Guide
 
     developer/localize
     developer/language-pack
+    developer/js-css
     Python Packages <developer/module/modules>
 
 This guide contains information for developers that want to modify or extend
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.
-- 
cgit v1.2.3