Add details on how to initiate a collection and add a helper function in support of that.

[shford]

Pretty much what the title says.

For a fledgling Anki developer writing a non-add-on program, it is not obvious, even after reading mounds of source code and docs, that one can find and pass your collection.anki2 path to Collection() to initialize a col.

Anki Forums, Reddit, and unsolved PRs/Issues on 3rd party projects such as genanki, panki, and others are full of advanced users although perhaps new to Anki searching for (and at times unnecessarily and unknowingly trying to duplicate) functionality that already readily exists via the official module. They just can’t figure out how to use it without building an add-on.

I understand this is hosted on a domain with “addon” literally in the name, and this change doesn't directly impact Anki add-on development. However, it could be useful knowledge for add-on developers for testing. Also these docs are the only thorough documentation on Anki extensibility via its official module. I think educating users on working with collections with external scripts via the Anki module certainly falls under extensibility and provides a gateway to making Anki add-ons.

[Updated] Regarding the helper function, it has now been tested on Linux, Mac, and Windows.

[abdnh]

This section does show how to initiate a collection: https://addon-docs.ankiweb.net/command-line-use.html

Your helper function can be simplified by using aqt.profiles.ProfileManager.get_created_base_folder().

[shford]

Thanks for the response! Evidently I did not browse through enough docs...

I think that kind of proves the point that the docs could be improved though, as I doubt I'm the only one who didn't find that page.

It seems to me that the CLI doc URL and site title do not describe its contents. It's not CLI usage; it's Python usage, specifically the anki module usage.

I think it makes much more sense to include the alternate way to initiate a collection in (The 'anki' Module)[https://addon-docs.ankiweb.net/the-anki-module.html] under the 'The Collection' section.

If you think these changes are too bulky to belong on the (The 'anki' Module)[https://addon-docs.ankiweb.net/the-anki-module.html] then maybe we could just move the alternate deck creation into the (ideally renamed) CLI documentation page? Then we could just drop a link to it on the (The 'anki' Module)[https://addon-docs.ankiweb.net/the-anki-module.html] page.

I'd be happy make the changes.

...Also I'm having some problems with aqt.profiles.ProfileManager.get_created_base_folder(). As best as I can tell this is supposed to reference the aqt module, however profiles does not exist. Is this something that will only exist inside an add-on? If so then I wouldn't consider that a full alternative to the helper function for people who are just using the module to generate/manipulate decks.

[abdnh]

It's not CLI usage; it's Python usage, specifically the anki module usage.

It shows usage outside the GUI, so the naming makes sense to me.

I think it makes much more sense to include the alternate way to initiate a collection in (The 'anki' Module)[https://addon-docs.ankiweb.net/the-anki-module.html] under the 'The Collection' section.

I think that's fine, but we can probably remove the helper function. Here's an example of the get_created_base_folder() method:

from aqt.profiles import ProfileManager

ProfileManager.get_created_base_folder(None)

As best as I can tell this is supposed to reference the aqt module, however profiles does not exist.

It definitely exists :) I'd recommend setting up VS Code/PyCharm and making use of their Python support. It'll also help you learn more about the anki/aqt modules without docs (because most stuff are undocumented)

[shford]

Okay, I removed the helper function and replaced it with the aqt function call as you've shown above.

If I try to run the snippet you've pasted above in pycharm I get an import error on running that says:
ModuleNotFoundError: No module named 'aqt.profiles'

The Pycharm hint highlighting agrees with this message. Hovering over the warning pops up with the message:
Cannot find reference 'profile' in '__init__.py'. This is with modules: anki v25.7.5, aqtp v0.9.0.