ateto 0.2.1
This is a set of tools to write templates outside of Anki.
Requires Python: >=3.10,<4.0
Keywords: anki,templates

Ateto : Anki templates tools
============================

`ateto` is a set of tools to write templates outside of Anki.

Why ?
-----

It's a collection of scripts I try to reorganize. It started with the Anki
addon called `Templates Import / Export
<https://ankiweb.net/shared/info/712027367>`_, a python tool, `Anki Template
Tester <https://github.com/klieret/anki-template-tester>`_ and now ... look at
this ! Yes, the name is not much creative.

In short, it can :

* **export models templates** (HTML and CSS) from Anki to
  files (inside `$XDG_DATA_HOME/ateto`)
* take some note as samples from Anki and **test the templates**
  with them (producing a file like `html_output/Basic.html`)
* **import** models templates and some shared medias (like `_base.css`)
  to Anki

From the command line, with something like this::

  ateto sync # export from anki
  ateto compile # write test templates files
  ateto sync -i # import in anki

There is also a shorthand command called ``ateto`` and a "watcher". It's useful
to compile test templates at each modification::

  ateto watch

Installation
------------

This should work::

  python -m pip install ateto

Requirements
~~~~~~~~~~~~

Right now it depends on the `AnkiConnect
<https://ankiweb.net/shared/info/2055492159>`_ Anki addon and
anki-templates-tester that I put inside this project to keep things simple.

Default working directory
-------------------------

The default working directory is `$XDG_DATA_HOME/ateto` (something like
`~/.local/share/ateto`). The templates of each Anki "note type" (or "model")
are stored in `models_export`.

Simple how to
-------------

Sync templates with Anki
~~~~~~~~~~~~~~~~~~~~~~~~

First, while Anki is running, we need to export models templates with
AnkiConnect::

  ateto sync

If we change some files in `models_export`, we can import them in Anki with::

  ateto sync -i

Compile test templates
~~~~~~~~~~~~~~~~~~~~~~

We need to get some sample data from Anki and then compile templates. But
first, open Anki and tag some notes with `template_test_data`::

  ateto populate
  ateto compile

Images and CSS or JS assets
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If there is missing images run::

  ateto link

All files under the `models_export/_medias` directory will be linked in
`html_output` with `compile -m`::

  ateto compile -m

But you have to create them first.

Supertemplates
~~~~~~~~~~~~~~

`models_export` contains template export of Anki notes templates. It's basic
HTML. There is "supertemplates" : it's Jinja2 templates that we can use to
generate the models, they are in `supertemplates` folder.

To build the supertemplates use `-s` option with `compile`::

  ateto compile -s

HTML and CSS files in supertemplates are processed, then `models_export` are
converted to `html_output`.

Watcher
~~~~~~~

It's my favorite part. When I'm working on some templates, I want modifications
to be automatically compiled in templates and output HTML some I use `watch`
command::

  ateto watch

And I want it all, supertemplates, medias and images. I want them to be
imported in Anki too. Images are only linked when starting, not watched ::

  ateto watch -ai

More
----

Debug mode
~~~~~~~~~~

`watch` and `compile` commands can be run with debug mode (`-d` option).
This will run supertemplates with a context where `is_debug=True`. It's
useful to debug AnkiDroid with something like this in templates files ::

  {% if is_debug %}
    <script src="https://cdn.jsdelivr.net/npm/eruda"></script>
    <script>eruda.init();</script>
  {% endif %}

File tree
~~~~~~~~~

So at the end, in `$XDG_DATA_HOME`, we have 4 main folders ::

* /supertemplates

  * ModelName/ directories

    * .jinja files
    * .html files
    * style.css file

  * _medias/ directory (optional)

    * .css files
    * .js files

* /models_export

  * ModelName/ directories

    * CardName.html files
    * style.css file

  * _medias/ directory (optional)

    * .css files
    * .js files

* /data

  * ModelName.yaml files
  * ModelName_override.yaml optional files

* /html_output

  * ModelName.html files
  * ModelName.css files
  * .css files linked from models_export/_medias
  * .js files linked from models_export/_medias
  * .png, .jpg, etc. files linked from anki_collection

The content of ``supertemplates`` is only created by hand and
compiled into ``models_export``.

All the content of ``models_export`` is synced with Anki (Ankiconnect). _medias
are treated with a special procedure.

The content of ``data`` is populated from Anki. _override.yaml files are
created by hand if necessary.

``html_output`` is the result of different actions :

* ModelName.html and ModelName.css files are the result of ``models_export``
  and ``data`` files
* others CSS or JS are linked to ``models_export/_medias``
* images are linked to the Anki collection