From a54d35f4890e1fe65c9e4b0fc832438f4cf1423d Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 16:53:12 -0400 Subject: [PATCH 1/8] Allow make script to be run with ./make.py on *NIX systems --- make.py | 1 + 1 file changed, 1 insertion(+) mode change 100644 => 100755 make.py diff --git a/make.py b/make.py old mode 100644 new mode 100755 index e4d670f95..bd3a74c2d --- a/make.py +++ b/make.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """ Build script for documentation """ From ca03b23d8746e2fcbdf1545ad6e96fd70b05e9c4 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 19:06:20 -0400 Subject: [PATCH 2/8] Cover enabling ./make.py syntax in CONTRIBUTING.md --- CONTRIBUTING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89bdf1f53..201c5ccbe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,6 +64,27 @@ Upgrade by running the following command: pip install --upgrade pip ``` +### Optional: Enable running the build script with `./make.py` on Mac & Linux + +On Mac & Linux, you can enable running `make.py` using `./make.py` instead +of `python make.py` as follows: + +1. Make sure you are in the root directory of the repo +2. Run `chmod +x make.py` + +You can now substitute `./make.py` anywhere the rest of this document +says `python make.py`. + +For example, this command: +```commandline +python make.py lint +``` + +can now be run this way: +```shell +./make.py lint +``` + ## Testing You should test your changes locally before submitting a pull request From 755dc1753a9b4c981fa7b5e030ea1222c2e0061a Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 19:30:33 -0400 Subject: [PATCH 3/8] Improve top-level docstring of make.py --- make.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/make.py b/make.py index bd3a74c2d..8c8590aea 100755 --- a/make.py +++ b/make.py @@ -1,6 +1,15 @@ #!/usr/bin/env python3 """ -Build script for documentation +Build script to simplify running: + +* Tests +* Code quality checks +* Documentation builds + +For help, see the following: + +* CONTRIBUTING.md +* The output of python make.py --help """ import os from contextlib import contextmanager From afab52bc1adb97ccba979ce78d24933db09c5a7c Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 20:04:55 -0400 Subject: [PATCH 4/8] Add shell completion setup instructions --- CONTRIBUTING.md | 34 +++++++++++++++++++++++++++++++++- make.py | 8 ++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 201c5ccbe..b9d2c6672 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,9 @@ Upgrade by running the following command: pip install --upgrade pip ``` -### Optional: Enable running the build script with `./make.py` on Mac & Linux +### Optional: Improve Ergonomics on Mac and Linux + +#### Enable `./make.py` On Mac & Linux, you can enable running `make.py` using `./make.py` instead of `python make.py` as follows: @@ -85,6 +87,36 @@ can now be run this way: ./make.py lint ``` +#### Enable Shell Completions + +After enabling the short-form syntax as outlined above, you can also enable tab +completion for commands on the following supported shells: + +* `bash` (the most common default shell) +* `zsh` +* `fish` +* `powershell` +* `powersh` + +For example, if you have typed the following... +```shell +./make.py h +``` + +Tab completion would allow you to press tab to auto-complete the command: +```shell +./make.py html +``` + +To enable this feature, most users can follow these steps: + +1. Run `./make.py whichshell` to find out what your default shell is +2. If it is one of the supported shells, run `./make.py --install-completion $(basename "$SHELL")` +3. Restart your terminal + +If your default shell is not the shell you prefer using for arcade development, +you may need to specify it to completion install command directly. + ## Testing You should test your changes locally before submitting a pull request diff --git a/make.py b/make.py index 8c8590aea..1d862b51d 100755 --- a/make.py +++ b/make.py @@ -454,5 +454,13 @@ def test(): run([PYTEST, UNITTESTS]) +@app.command() +def whichshell(): + """to find out which shell your system seems to be running""" + + shell_name = Path(os.environ.get('SHELL')).stem + print(f"Your current shell appears to be: {shell_name}") + + if __name__ == "__main__": app() From 0dde5db150ca6e50fe2b9ad725120d3ef380923d Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 20:13:27 -0400 Subject: [PATCH 5/8] Move optional Mac & Linux instructions to the end of CONTRIBUTING.md --- CONTRIBUTING.md | 106 ++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 52 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9d2c6672..3063b9df3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,58 +64,8 @@ Upgrade by running the following command: pip install --upgrade pip ``` -### Optional: Improve Ergonomics on Mac and Linux - -#### Enable `./make.py` - -On Mac & Linux, you can enable running `make.py` using `./make.py` instead -of `python make.py` as follows: - -1. Make sure you are in the root directory of the repo -2. Run `chmod +x make.py` - -You can now substitute `./make.py` anywhere the rest of this document -says `python make.py`. - -For example, this command: -```commandline -python make.py lint -``` - -can now be run this way: -```shell -./make.py lint -``` - -#### Enable Shell Completions - -After enabling the short-form syntax as outlined above, you can also enable tab -completion for commands on the following supported shells: - -* `bash` (the most common default shell) -* `zsh` -* `fish` -* `powershell` -* `powersh` - -For example, if you have typed the following... -```shell -./make.py h -``` - -Tab completion would allow you to press tab to auto-complete the command: -```shell -./make.py html -``` - -To enable this feature, most users can follow these steps: - -1. Run `./make.py whichshell` to find out what your default shell is -2. If it is one of the supported shells, run `./make.py --install-completion $(basename "$SHELL")` -3. Restart your terminal - -If your default shell is not the shell you prefer using for arcade development, -you may need to specify it to completion install command directly. +Mac & Linux users can improve their development experience further by following the optional +steps at the end of this document. ## Testing @@ -188,3 +138,55 @@ python -m http.server -d doc/build/html You can now open [http://localhost:8000](http://localhost:8000) in your browser to preview the doc. Be sure to re-run build & refresh to update after making changes! + +## Optional: Improve Ergonomics on Mac and Linux + +### Enable `./make.py` + +On Mac & Linux, you can enable running `make.py` using `./make.py` instead +of `python make.py` as follows: + +1. Make sure you are in the root directory of the repo +2. Run `chmod +x make.py` + +You can run the make script with `./make.py` instead of `python make.py`. + +For example, this command: +```commandline +python make.py lint +``` + +can now be run this way: +```shell +./make.py lint +``` + +### Enable Shell Completions + +After enabling the short-form syntax as outlined above, you can also enable tab +completion for commands on the following supported shells: + +* `bash` (the most common default shell) +* `zsh` +* `fish` +* `powershell` +* `powersh` + +For example, if you have typed the following... +```shell +./make.py h +``` + +Tab completion would allow you to press tab to auto-complete the command: +```shell +./make.py html +``` + +To enable this feature, most users can follow these steps: + +1. Run `./make.py whichshell` to find out what your default shell is +2. If it is one of the supported shells, run `./make.py --install-completion $(basename "$SHELL")` +3. Restart your terminal + +If your default shell is not the shell you prefer using for arcade development, +you may need to specify it to the completion install command directly. From 7d4b9dc87acf3020e533959da92875fbf94f2e8b Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 20:18:00 -0400 Subject: [PATCH 6/8] Make execution permission user-specific --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3063b9df3..271e2d6ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,7 +147,7 @@ On Mac & Linux, you can enable running `make.py` using `./make.py` instead of `python make.py` as follows: 1. Make sure you are in the root directory of the repo -2. Run `chmod +x make.py` +2. Run `chmod u+x make.py` You can run the make script with `./make.py` instead of `python make.py`. From 8325984ad64fe23bd83615d17e8e7050ac2bab72 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 20:40:02 -0400 Subject: [PATCH 7/8] Improve whichshell subcommand --- make.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/make.py b/make.py index 1d862b51d..f6a0d9b22 100755 --- a/make.py +++ b/make.py @@ -454,12 +454,25 @@ def test(): run([PYTEST, UNITTESTS]) +SHELLS_WITH_AUTOCOMPLETE = ( + 'bash', + 'zsh', + 'fish', + 'powershell', + 'powersh' +) + + @app.command() def whichshell(): """to find out which shell your system seems to be running""" shell_name = Path(os.environ.get('SHELL')).stem - print(f"Your current shell appears to be: {shell_name}") + print(f"Your default shell appears to be: {shell_name}") + + if shell_name in SHELLS_WITH_AUTOCOMPLETE: + print("This shell is known to support tab-completion!") + print("See CONTRIBUTING.md for more information on how to enable it.") if __name__ == "__main__": From 2155a5b014f2d3862b71cd4ceddee839833940a9 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Sat, 29 Apr 2023 20:43:09 -0400 Subject: [PATCH 8/8] Tweak phrasing at end of CONTRIBUTING.md --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 271e2d6ad..86e2eca2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -189,4 +189,5 @@ To enable this feature, most users can follow these steps: 3. Restart your terminal If your default shell is not the shell you prefer using for arcade development, -you may need to specify it to the completion install command directly. +you may need to specify it to the command above directly instead of using +autodetection.