diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel new file mode 100644 index 000000000..23af06ebb --- /dev/null +++ b/docs/BUILD.bazel @@ -0,0 +1,4 @@ +load("//ts:prettier.bzl", "prettier_test") + +# formatting of the .md files +prettier_test() diff --git a/docs/architecture.md b/docs/architecture.md index 60ff0aaac..f0e255217 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -21,7 +21,7 @@ pylib contains a private Python module called rsbridge (`pylib/rsbridge/`) that ### GUI -Anki's *GUI* is a mix of Qt (via the PyQt Python bindings for Qt), and +Anki's _GUI_ is a mix of Qt (via the PyQt Python bindings for Qt), and TypeScript/HTML/CSS. The Qt code lives in `qt/aqt/`, and is importable in Python with "import aqt". The web code is split between `qt/aqt/data/web/` and `ts/`, with the majority of new code being placed in the latter, and copied into the @@ -39,4 +39,4 @@ type-safe manner between the different languages. At the moment, the protobuf is not considered public API. Some pylib methods expose a protobuf object directly to callers, but when they do so, they use a type alias, so callers outside pylib should never need to import a generated -_pb2.py file. +\_pb2.py file. diff --git a/docs/development.md b/docs/development.md index eac8d36c2..1bca914c7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -179,9 +179,9 @@ expand proc macros and build scripts, and run cargo check on startup. Adding of `use` statements. The Bazel build products will make RA start up slowly out of the box. For a much -nicer experience, add each of the bazel-* folders to Rust Analyzer's excludeDirs -settings, and node_modules. Wildcards don't work unfortunately. Then adjust -VS Code's "watcher exclude", and add `**/bazel-*`. +nicer experience, add each of the `bazel-*` folders to Rust Analyzer's excludeDirs +settings, and node*modules. Wildcards don't work unfortunately. Then adjust +VS Code's "watcher exclude", and add `\*\*/bazel-*`. After running 'code' from the project root, it may take a minute or two to be ready. diff --git a/docs/docker/README.md b/docs/docker/README.md index ae36fe76b..eb28a1905 100644 --- a/docs/docker/README.md +++ b/docs/docker/README.md @@ -59,7 +59,7 @@ docker run --rm -it \ Here is a breakdown of some of the arguments: -- Mount the current user's `~/.local/share` directory onto the container. Anki saves things +- Mount the current user's `~/.local/share` directory onto the container. Anki saves things into this directory, and if we don't mount it, we will lose any changes once the container exits. We mount this as read-write (`rw`) because we want to make changes here. @@ -67,26 +67,26 @@ Here is a breakdown of some of the arguments: --volume $HOME/.local/share:$HOME/.local/share:rw ``` -- Mount `/etc/passwd` so we can enter the container as ourselves. We mount this as +- Mount `/etc/passwd` so we can enter the container as ourselves. We mount this as read-only because we definitely do not want to modify this. ```bash --volume /etc/passwd:/etc/passwd:ro ``` -- Enter the container with our user ID and group ID, so we stay as ourselves. +- Enter the container with our user ID and group ID, so we stay as ourselves. ```bash --user $(id -u):$(id -g) ``` -- Mount the X11 directory that allows us to open displays. +- Mount the X11 directory that allows us to open displays. ```bash --volume /tmp/.X11-unix:/tmp/.X11-unix:rw ``` -- Pass the `DISPLAY` variable to the container, so it knows where to display graphics. +- Pass the `DISPLAY` variable to the container, so it knows where to display graphics. ```bash --env DISPLAY=$DISPLAY diff --git a/docs/new-platform.md b/docs/new-platform.md index ffdb67bb1..a34c9823f 100644 --- a/docs/new-platform.md +++ b/docs/new-platform.md @@ -2,12 +2,12 @@ ## Upstream prerequisites -- A recent Qt, PyQt5 and PyQtWebEngine must work on your platform. Chances are wheels - for your platform are not available on PyPI, so you will need to have a working - version installed already, either from your Linux distro's archives, or by building - from source. -- Rust and Node must support your platform. -- If the Bazel Rust and Node rules do not support your platform, extra work may be required. +- A recent Qt, PyQt5 and PyQtWebEngine must work on your platform. Chances are wheels + for your platform are not available on PyPI, so you will need to have a working + version installed already, either from your Linux distro's archives, or by building + from source. +- Rust and Node must support your platform. +- If the Bazel Rust and Node rules do not support your platform, extra work may be required. ## 32 bit builds @@ -17,47 +17,47 @@ tried, and it will likely not work out of the box. ## Protobuf & Python -- Edit /platforms/BUILD.bzl and add the new platform. Available platforms - and CPUs can be found here: https://github.com/bazelbuild/platforms -- Edit /protobuf.bzl and add the new platform and a link to a protoc binary. -- Edit /pylib/anki/BUILD.bazel and add the new platform and the relevant - Python wheel name for your platform. +- Edit /platforms/BUILD.bzl and add the new platform. Available platforms + and CPUs can be found here: https://github.com/bazelbuild/platforms +- Edit /protobuf.bzl and add the new platform and a link to a protoc binary. +- Edit /pylib/anki/BUILD.bazel and add the new platform and the relevant + Python wheel name for your platform. Example of the above changes: https://github.com/ankitects/anki/commit/db3308e788f20b188e84add40d6a1dce5bf726a0 -- We need to tell the build process to use your local PyQt5 install, instead of - fetching it from PyPI. Locate your Python site-packages folder where the PyQt5 - folder is, and add the following to user.bazelrc in the project folder root: +- We need to tell the build process to use your local PyQt5 install, instead of + fetching it from PyPI. Locate your Python site-packages folder where the PyQt5 + folder is, and add the following to user.bazelrc in the project folder root: ``` -build --action_env=PYTHON_SITE_PACKAGES=/path/to/site-packages +build --action_env=PYTHON_SITE_PACKAGES=/path/to/site-packages/ ``` -- Anki uses the Python 'orjson' module to speed up DB access. If you're on a - platform that can not build orjson, you can remove it from - pip/requirements.txt to skip it during running/building, but DB operations - will be slower. +- Anki uses the Python 'orjson' module to speed up DB access. If you're on a + platform that can not build orjson, you can remove it from + python/requirements.txt to skip it during running/building, but DB operations + will be slower. - The py_wheel() rule in pylib/anki/BUILD.bazel adds an orjson requirement to - the generated Anki wheel on x86_64. If you have removed orjson, you'll want to - remove that line. If you have successfully built orjson for another platform, - you'll want to adjust that line to include your platform. + The py_wheel() rule in pylib/anki/BUILD.bazel adds an orjson requirement to + the generated Anki wheel. If you have removed orjson, you'll want to + remove that line. If you have successfully built orjson for another platform, + you'll want to adjust that line to include your platform. ## Rust -- Ensure you have Rust installed (eg via rustup) -- Edit /Cargo.toml in this project, and add your platform - to the targets. Check that the platform [is supported](https://github.com/bazelbuild/rules_rust/blob/master/rust/platform/platform.bzl) by rules_rust; if it is not, you'll - need to send a PR to them adding it. You can test your change locally by modifying - /repos.bzl in this project to point to a local rules_rust checkout. -- Edit /cargo/BUILD.request.bazel and add the new platform. -- Run update.py in the /cargo folder. +- Ensure you have Rust installed (eg via rustup) +- Edit /Cargo.toml in this project, and add your platform + to the targets. Check that the platform [is supported](https://github.com/bazelbuild/rules_rust/blob/master/rust/platform/platform.bzl) by rules_rust; if it is not, you'll + need to send a PR to them adding it. You can test your change locally by modifying + /repos.bzl in this project to point to a local rules_rust checkout. +- Edit /cargo/BUILD.request.bazel and add the new platform. +- Run update.py in the /cargo folder. Examples of the required changes: -- https://github.com/ankitects/anki/commit/eca27b371000e77b68cb4c790b44848507ca3883 -- https://github.com/ankitects/anki/commit/3f3f4b5c3640a7d1f4eec02f326fda93214ec34b +- https://github.com/ankitects/anki/commit/eca27b371000e77b68cb4c790b44848507ca3883 +- https://github.com/ankitects/anki/commit/3f3f4b5c3640a7d1f4eec02f326fda93214ec34b ## NodeJS diff --git a/docs/syncserver.md b/docs/syncserver.md index 6b2e5f54e..23c2afe34 100644 --- a/docs/syncserver.md +++ b/docs/syncserver.md @@ -5,21 +5,21 @@ use AnkiWeb, you can run the server on a machine on your local network. Things to be aware of: -- Media syncing is not currently supported. You will either need to disable - syncing of sounds and images in the preferences screen, sync your media via - AnkiWeb, or use some other solution. -- AnkiMobile does not yet provide an option for using a local sync server, - so for now this will only be usable with the computer version of Anki, and - AnkiDroid. -- This code is partly new, and while it has had some testing, it's possible - something has been missed. Please make backups, and report any bugs you run - into. -- The server runs over an unencrypted HTTP connection and does not require - authentication, so it is only suitable for use on a private network. -- This is an advanced feature, targeted at users who are comfortable with - networking and the command line. If you use this, the expectation is you - can resolve any setup/network/firewall issues you run into yourself, and - use of this is entirely at your own risk. +- Media syncing is not currently supported. You will either need to disable + syncing of sounds and images in the preferences screen, sync your media via + AnkiWeb, or use some other solution. +- AnkiMobile does not yet provide an option for using a local sync server, + so for now this will only be usable with the computer version of Anki, and + AnkiDroid. +- This code is partly new, and while it has had some testing, it's possible + something has been missed. Please make backups, and report any bugs you run + into. +- The server runs over an unencrypted HTTP connection and does not require + authentication, so it is only suitable for use on a private network. +- This is an advanced feature, targeted at users who are comfortable with + networking and the command line. If you use this, the expectation is you + can resolve any setup/network/firewall issues you run into yourself, and + use of this is entirely at your own risk. ## From source diff --git a/ts/format.sh b/ts/format.sh index 1f66bd492..816699524 100755 --- a/ts/format.sh +++ b/ts/format.sh @@ -1,2 +1,7 @@ # this is a hack to invoke prettier directly from Bazel -(cd "${BUILD_WORKSPACE_DIRECTORY}" && node_modules/.bin/prettier --config .prettierrc --write ts qt/aqt/data/web/js) +(cd "${BUILD_WORKSPACE_DIRECTORY}" && node_modules/.bin/prettier \ + --config .prettierrc --write \ + ts \ + qt/aqt/data/web/js \ + docs \ + ) diff --git a/ts/prettier.bzl b/ts/prettier.bzl index f2512d634..26bc7ab6e 100644 --- a/ts/prettier.bzl +++ b/ts/prettier.bzl @@ -9,6 +9,7 @@ def prettier_test(name = "format_check", srcs = None, exclude = [], **kwargs): "*.ts", "*.js", "*.svelte", + "*.md", ], exclude = exclude) _prettier_test(