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) and jinja
(for everything else),
through the tools/make.py
script.
You must build the note to use compile-time options.
Additionally, if you want to use bleeding edge features
(the absolute latest features, which are potentially 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. and have a lower version of Python.
- sass (dart implementation)
- The dart implementation is required to use the latest features of sass.
- Anki 2.1.49 or higher (2.1.54+ is highly recommended)
- Anki-Connect addon
Initialization¶
The following creates a custom python environment with venv
,
so that packages aren't installed into your global python environment.
# on fresh installs
git clone https://github.com/Aquafina-water-bottle/jp-mining-note.git
cd jp-mining-note
# alternatively, if you already have the repository on your system:
git pull origin/master
# You may have to use `python` instead of `python3`, and `pip` instead of `pip3`.
python3 -m 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 ./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):
Note
The master
branch is the stable version of the note.
If you want to build the bleeding edge version of the note,
use the dev
branch. For example, do the following:
Building and Installing¶
After setting up the venv
, you are ready to build and install the note.
cd tools
# builds the note into the ./build folder
python3 make.py
# installs the note from the ./build folder
# WARNING: completely overrides current note that is installed!
# Please make a backup of your collection before doing this!
python3 install.py --from-build --update
Warning
If you are attempting to (build and) install the bleeding edge (dev
) version of the note
at ALL, use the --dev-output-version="0.12.0.0"
flag on the
install.py
(or main.py
) script. For example:
There are also some related notes for the current dev build:
-
If you're on 2.1.54 or below, you'll want to add
legacy-anki_2-1-54
to thecss-folders
of the config.py, i.e. -
The font size of some fields aren't automatically changed yet, so you'll have to adjust them manually in order for it to look nice:
-
In addition to the above, you would likely want to match the font family with all the other fields, as the font family for new fields is not updated either.
Note
Running the main.py
script is exactly equivalent of running the above two commands.
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