Improve make script ergonomics & documentation (#1739)

* Allow make script to be run with ./make.py on *NIX systems

* Cover enabling ./make.py syntax in CONTRIBUTING.md

* Improve top-level docstring of make.py

* Add shell completion setup instructions

* Move optional Mac & Linux instructions to the end of CONTRIBUTING.md

* Make execution permission user-specific

* Improve whichshell subcommand

* Tweak phrasing at end of CONTRIBUTING.md

Author: pushfoo

CONTRIBUTING.md

@@ -64,6 +64,9 @@ Upgrade by running the following command:
 pip install --upgrade pip
 ```
 
+Mac & Linux users can improve their development experience further by following the optional
+steps at the end of this document.
+
 ## Testing
 
 You should test your changes locally before submitting a pull request
@@ -135,3 +138,56 @@ 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 u+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 command above directly instead of using
+autodetection.

make.py

@@ -1,5 +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
@@ -444,5 +454,26 @@ 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 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__":
     app()