diff options
| -rw-r--r-- | doc/developer.rst | 1 | ||||
| -rw-r--r-- | doc/developer/js-css.rst | 60 |
2 files changed, 61 insertions, 0 deletions
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. |