refactor: move commands into bin and write Makefile to run them

Author: gvwilson

CONTRIBUTING.md

@@ -19,7 +19,7 @@ it is important to understand the structure of the code and the repository.
 -   The [`plotly.graph_objects`](https://plotly.com/python/graph-objects/) module (usually imported as `go`)
     is [generated from the plotly.js schema](https://plotly.com/python/figure-structure/),
     so changes to be made in this package need to be contributed to [plotly.js](https://github.com/plotly/plotly.js)
-    or to the code generation system in `./codegen/`.
+    or to the code generation system in `./bin/codegen/`.
     Code generation creates traces and layout classes that have a direct correspondence to their JavaScript counterparts,
     while higher-level methods that work on figures regardless of the current schema (e.g., `BaseFigure.for_each_trace`)
     are defined in `plotly/basedatatypes.py`.
@@ -42,12 +42,13 @@ it is important to understand the structure of the code and the repository.
     The documentation is a great place to start contributing,
     since you can add or modify examples without setting up a full environment.
 
-Code and documentation are not the only way to contribute:
-you can also help by:
+Code and documentation are not the only way to contribute.
+You can also help by:
 
 -   Reporting bugs at <https://github.com/plotly/plotly.py/issues>.
     Please take a moment to see if your problem has already been reported, and if so, add a comment to the existing issue;
-    we will try to prioritize those that affect the most people.
+    we will try to prioritize those that affect the most people
+    and that are accompanied by small, runnable examples.
 
 -   Submitting feature requests (also at <https://github.com/plotly/plotly.py/issues>).
     Again, please add a comment to an existing issue if the feature you want has already been requested.
@@ -219,11 +220,11 @@ Once you have done that,
 run the `updateplotlyjs` command:
 
 ```bash
-python commands.py updateplotlyjs
+python bin/updatejs.py
 ```
 
 This downloads new versions of `plot-schema.json` and `plotly.min.js` from the `plotly/plotly.js` GitHub repository
-and places them in `plotly/package_data`.
+and places them in `resources` and `plotly/package_data` respectively.
 It then regenerates all of the `graph_objs` classes based on the new schema.
 
 ### Using a Development Branch of Plotly.js
@@ -232,7 +233,8 @@ If your development branch is in [the plotly.js repository](https://github.com/p
 you can update to development versions of `plotly.js` with this command:
 
 ```bash
-python commands.py updateplotlyjsdev --devrepo reponame --devbranch branchname
+# FIXME commands.py didn't provide --devrepo or --devbranch
+python bin/updatejs.py --dev --devrepo reponame --devbranch branchname
 ```
 
 This fetches the `plotly.js` in the CircleCI artifact of the branch `branchname` of the repo `reponame`.
@@ -255,5 +257,6 @@ You can then run the following command
 *in your local plotly.py repository*:
 
 ```bash
-python commands.py updateplotlyjsdev --local /path/to/your/plotly.js/
+# FIXME: commands.py didn't provide --local
+python bin/updatejs.py --dev --local /path/to/your/plotly.js/
 ```

Makefile

@@ -0,0 +1,48 @@
+# Manage snailz project.
+
+PYTHON = uv run python
+CODE_DIRS = _plotly_utils plotly scripts
+
+## commands: show available commands
+commands:
+	@grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':'
+
+## docs: rebuild documentation
+.PHONY: docs
+docs:
+	${PYTHON} -m mkdocs build
+
+## format: reformat code
+format:
+	${PYTHON} -m ruff format ${CODE_DIRS}
+
+## generate: generate code
+generate:
+	${PYTHON} bin/generate_code.py --codedir plotly
+
+## lint: check the code
+lint:
+	${PYTHON} -m ruff check ${CODE_DIRS}
+
+## test: run tests
+test:
+	${PYTHON_M} pytest tests
+
+## updatejs: update JavaScript bundle
+updatejs:
+	${PYTHON} bin/updatejs.py --codedir plotly
+
+## --: --
+
+## clean: clean up repository
+clean:
+	@find . -name '*~' -delete
+	@find . -name '.DS_Store' -delete
+	@rm -rf .coverage
+	@rm -rf .pytest_cache
+	@rm -rf .ruff_cache
+	@rm -rf dist
+
+## sync: update Python packages
+sync:
+	uv sync --extra dev

README.md

@@ -76,22 +76,21 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
 
 ## Installation
 
-plotly.py may be installed using pip
+plotly.py may be installed using pip:
 
 ```
 pip install plotly
 ```
 
-or conda.
+or conda:
 
 ```
 conda install -c conda-forge plotly
 ```
 
 ### Jupyter Widget Support
 
-For use as a Jupyter widget, install `jupyter` and `anywidget`
-packages using `pip`:
+For use as a Jupyter widget, install the `jupyter` and `anywidget` packages using `pip`:
 
 ```
 pip install jupyter anywidget
@@ -112,14 +111,14 @@ command line utility (legacy as of `plotly` version 4.9).
 
 #### Kaleido
 
-The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
-using pip
+The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies
+and can be installed using pip:
 
 ```
 pip install -U kaleido
 ```
 
-or conda
+or conda:
 
 ```
 conda install -c conda-forge python-kaleido
@@ -129,13 +128,13 @@ conda install -c conda-forge python-kaleido
 
 Some plotly.py features rely on fairly large geographic shape files. The county
 choropleth figure factory is one such example. These shape files are distributed as a
-separate `plotly-geo` package. This package can be installed using pip...
+separate `plotly-geo` package. This package can be installed using pip:
 
 ```
 pip install plotly-geo==1.0.0
 ```
 
-or conda
+or conda:
 
 ```
 conda install -c plotly plotly-geo=1.0.0
@@ -145,7 +144,7 @@ conda install -c plotly plotly-geo=1.0.0
 
 ## Copyright and Licenses
 
-Code and documentation copyright 2019 Plotly, Inc.
+Code and documentation copyright Plotly, Inc.
 
 Code released under the [MIT license](https://github.com/plotly/plotly.py/blob/main/LICENSE.txt).
 

codegen/__init__.py renamed to bin/codegen/__init__.py

@@ -96,18 +96,6 @@ def make_paths(outdir):
     return validators_dir, graph_objs_dir, graph_objects_path
 
 
-def lint_code(outdir):
-    """Check Python code using settings in pyproject.toml."""
-
-    subprocess.call(["ruff", "check", *make_paths(outdir)])
-
-
-def reformat_code(outdir):
-    """Reformat Python code using settings in pyproject.toml."""
-
-    subprocess.call(["ruff", "format", *make_paths(outdir)])
-
-
 def perform_codegen(outdir, noformat=False):
     """Generate code (and possibly reformat)."""
 
@@ -123,7 +111,7 @@ def perform_codegen(outdir, noformat=False):
     # Load plotly schema
     project_root = opath.dirname(outdir)
     plot_schema_path = opath.join(
-        project_root, "codegen", "resources", "plot-schema.json"
+        project_root, "resources", "plot-schema.json"
     )
 
     with open(plot_schema_path, "r") as f:

codegen/compatibility.py renamed to bin/codegen/compatibility.py

@@ -0,0 +1,28 @@
+"""Generate code."""
+
+import argparse
+
+import utils
+
+
+def main():
+    """Main driver."""
+
+    args = parse_args()
+    codedir = utils.select_code_directory(args)
+    utils.perform_codegen(codedir, noformat=args.noformat)
+
+
+def parse_args():
+    """Parse command-line arguments."""
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--noformat", action="store_true", help="prevent reformatting"
+    )
+    parser.add_argument("--codedir", type=str, help="code directory")
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    main()