Skip to content

Latest commit

 

History

History
70 lines (46 loc) · 2.71 KB

CONTRIBUTING.md

File metadata and controls

70 lines (46 loc) · 2.71 KB
Raw

Contributing

Development

Setup

See README for details about how to install with hatch virtualenv.

Developing the ZIM UI in Vue.JS

When you want to alter something in the ZIM UI in Vue.JS, you need assets which are generated by the scraper (e.g. shared.json, ...).

To simplify this, it is possible to:

  • run the scraper (with original code base or your modified one)
  • extract assets from generated files and place them in a directory where ZIM UI will find them
  • iterate on ZIM UI code

This needs to be done everytime you make significant changes to the scraper (Python code) that have impact on files used by the Vue.JS UI.

To achieve this, first build the Docker image based on current code base.

docker build -t local-mindtouch .

Scrape a library (here we use the Geosciences library, with only page id 28207 and its children but you could use any other one of interest for your UI developments).

docker run --rm -it -v "$PWD/output":/output local-mindtouch mindtouch2zim --library-url https://geo.libretexts.org --name libretexts.org_en_geo --creator LibreTexts --title "LibreTexts Geosciences" --description "Geosciences courses from libretexts.org" --file-name tests_en_libretexts-geo --root-page-id 28207 --overwrite

Extract interesting ZIM content and move it to public folder.

rm -rf zimui/public/content zimui/public/mathjax
docker run -it --rm -v $(pwd)/output:/data ghcr.io/openzim/zim-tools:latest zimdump dump --dir=/data/tests_en_libretexts-geo /data/tests_en_libretexts-geo.zim
sudo chown -R $(id -u -n):$(id -g -n) output/tests_en_libretexts-geo
mv output/tests_en_libretexts-geo/content output/tests_en_libretexts-geo/mathjax zimui/public
rm -rf output/tests_en_libretexts-geo

Start ZIM UI locally.

cd zimui
yarn dev

Do not forget to cleanup public/content folder before building the docker image again, otherwise all assets will be pushed to the ZIM.

Note that some assets (e.g. icomoon fonts on LibreTexts Geoscience) having a question mark in their URL are not properly working in the yarn dev server. This is OK inside the ZIM. See #34.

rm -rf zimui/public/content

testing with cypress

Cypress is used for end-to-end testing of the ZIM UI. It allows you to write tests that simulate user interactions with the application to ensure everything works as expected.

To run the tests, you need to start the ZIM UI locally and then run the tests.

cd zimui
yarn dev
yarn test:e2e

On Linux, you might need to install additional dependencies, see Linux Prerequisites in the Cypress documentation.