Building
Technical Summary¶
The Anki card template is generated through jinja
templates,
which is a popular templating engine for Python
.
All of these templates are located under the (root)/src
folder.
The Anki templates are generated through a combination of
sass
(for CSS), jinja
(for HTML generation),
and npm
(Webpack + TypeScript) for JavaScript generation.
All of this is managed through the tools/make.py
script.
You must build the note to use any compile options.
Additionally, if you want to use bleeding edge features
(the absolute latest features, which maybe riddled with bugs),
you must build and install the note from the dev
branch.
More info about this is shown later.
Note
The instructions listed below will be primarily Linux based. Notes for other operating systems may be shown, but are not guaranteed.
It is also assumed that you have knowledge of basic command line.
Building¶
Prerequisites¶
- Python 3.10.6 or higher
- I recommend pyenv to upgrade your python version if you're running Linux.
- git
- npm
- Anki-Connect
- Anki 2.1.54+ or higher
Initialization (git)¶
First, you must clone the repository onto your drive.
# on fresh installs
git clone https://github.com/arbyste/jp-mining-note.git
cd jp-mining-note
# alternatively, if you already have the repository on your system:
git pull origin master
The master
branch is the stable version of the note.
If you want to build the pre-release version of the note,
use the dev
branch. For example, do the following:
Initialization (venv)¶
The following creates a custom python environment with venv
,
so that packages aren't installed into your global python environment.
# assuming you are under the root folder, usu. jp-mining-note
# You may have to use `python` instead of `python3`, and `pip` instead of `pip3`.
python3 -m venv .venv
# The following is for POSIX (bash/zsh) only.
# See how to activate venv on your system in the official documentation:
# https://docs.python.org/3/library/venv.html
source ./.venv/bin/activate
pip3 install -r tools/requirements.txt
Some additional options with venv
are shown below.
Resetting the venv
Don't want to use venv?
It is highly recommended that you use venv, or something else that isolates the python environment.
However, in case you don't want to use venv
,
you can manually install the dependencies
(including dependencies for building documentation):
Initialization (npm)¶
The following installs all the required dependencies for generating the note's JavaScript.
Building and Installing¶
After setting up venv
and npm
, you are ready to build and install the note.
# Builds the note into the (root)/build folder, and installs.
# WARNING: completely overrides current note that is installed!
# Please make a backup of your collection before doing this!
python3 tools/main.py
Note
If you are attempting to (build and) install the bleeding edge version of the note on an Anki profile that does NOT already have the note installed, you have to run the installation script twice. For example:
Additional things you can do with the project are shown below.
Running Tests¶
Building the Documentation¶
To "build" the documentation, all you have to do is the following:
This will allow you to preview the website (usually at http://127.0.0.1:8000/jp-mining-note/
).
If you are looking to edit the documentation, all related files should be found
under this docs
folder.
The important markdown files are found under:
Common Errors¶
(TODO) Fill this out as people start working with this note