From fcdc51aace493fd5c2b8d3bf4e30980fbdb2f3bb Mon Sep 17 00:00:00 2001
From: Damien Elmes <gpg@ankiweb.net>
Date: Mon, 7 Dec 2020 11:22:31 +1000
Subject: [PATCH] add explicit entry point to start Anki; update docs

---
 docs/development.md | 81 ++++++++++++++++++++++++++++++---------------
 qt/aqt/BUILD.bazel  |  3 ++
 2 files changed, 57 insertions(+), 27 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index 78c75cd07..e9d73d4a7 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -2,35 +2,52 @@
 
 ## Packaged betas
 
-For non-developers who want to try this development code, the easiest way is
-to use a packaged version - please see:
+For non-developers who want to try beta versions, the easiest way is to use a
+packaged version - please see:
 
 https://betas.ankiweb.net/#/
 
-You are welcome to run Anki from source instead, but it is expected that you can
-sort out issues by yourself - we are not able to provide support for problems
-you encounter when running from source.
-
 ## Pre-built Python wheels
 
-If you want to run Anki from a local Python installation but don't want
-to make changes to the source code, you can install pre-built packages from PyPI.
+Pre-built Python packages are available on PyPI. They are useful if you wish to:
 
-For older versions:
+- Run Anki from a local Python installation without building it yourself
+- Get code completion when developing add-ons
+- Make command line scripts that modify .anki2 files via Anki's Python libraries
+
+You will need Python 3.8 or 3.9 installed. If you do not have Python yet, please
+see the platform-specific instructions in the "Building from source" section below
+for more info.
+
+The instructions below are for Anki 2.1.36+.
+
+**Mac/Linux**:
 
 ```
-$ python -m venv pyenv
-$ pyenv/bin/pip install aqt anki ankirspy pyqt5 pyqtwebengine
-$ pyenv/bin/python -c 'import aqt; aqt.run()'
+$ python3.8 -m venv ~/pyenv
+$ ~/pyenv/bin/pip install --upgrade pip
+$ ~/pyenv/bin/pip install aqt
 ```
 
-From Anki 2.1.36 onwards:
+Then to run Anki:
 
 ```
-$ python -m venv pyenv
-$ pyenv/bin/pip install --upgrade pip
-$ pyenv/bin/pip install aqt
-$ pyenv/bin/python -c 'import aqt; aqt.run()'
+$ ~/pyenv/bin/anki
+```
+
+**Windows**:
+
+```
+c:\> python -m venv \pyenv
+c:\> \pyenv\scripts\activate
+c:\> \pyenv\scripts\pip install --upgrade pip
+c:\> \pyenv\scripts\pip install aqt
+```
+
+Then to run Anki:
+
+```
+c:\> \pyenv\scripts\anki
 ```
 
 ## Building from source
@@ -48,6 +65,26 @@ Before contributing code, please see [Contributing](./contributing.md).
 
 If you'd like to contribute translations, please see <https://translating.ankiweb.net/#/>.
 
+## Building redistributable wheels
+
+Run the following commands to create Python packages that can be redistributed
+and installed:
+
+```
+bazel build -c opt //pylib/anki:wheel
+bazel build -c opt //qt/aqt:wheel
+```
+
+The generated wheel paths will be printed as the build completes.
+
+You can then install them by copying the paths into a pip install command.
+Follow the steps in the "Pre-built Python wheels" section above, but replace the
+"pip install aqt" line with something like:
+
+```
+pip install /path/to/anki.whl /path/to/aqt.whl
+```
+
 ## Running tests
 
 From inside the source folder:
@@ -77,16 +114,6 @@ If you're in one of those folders, you can use the short form:
 bazel run format
 ```
 
-## Building redistributable wheels
-
-```
-bazel build -c opt //pylib/anki:wheel
-bazel build -c opt //qt/aqt:wheel
-```
-
-The generated wheel paths will be printed as the build completes. You can install
-them with pip.
-
 ## Audio
 
 Audio playing requires `mpv` or `mplayer` to be in your system path.
diff --git a/qt/aqt/BUILD.bazel b/qt/aqt/BUILD.bazel
index 675a38c54..0b6ae72fd 100644
--- a/qt/aqt/BUILD.bazel
+++ b/qt/aqt/BUILD.bazel
@@ -87,6 +87,9 @@ py_wheel(
     name = "wheel",
     description_file = "wheel_description.txt",
     distribution = "aqt",
+    entry_points = {
+        "console_scripts": ["anki = aqt:run"],
+    },
     homepage = "https://apps.ankiweb.net",
     license = "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
     python_tag = "py3",