feat: converting documentation to mkdocs

.gitignore

@@ -13,6 +13,9 @@ tests/test_orca/images/linux/failed/
 
 doc/python/raw.githubusercontent.com/
 
+docs/
+docs_tmp/
+
 # Don't ignore dataset files
 !*.csv.gz
 !*.geojson.gz
@@ -59,6 +62,8 @@ doc/python/.mapbox_token
 doc/.ipynb_checkpoints
 tags
 doc/check-or-enforce-order.py
+files.figshare.com
+*.zip
 
 tests/percy/*.html
 tests/percy/pandas2/*.html

CONTRIBUTING.md

@@ -8,7 +8,7 @@ then explains the technical aspects of preparing your contribution.
 
 ## Code of Conduct
 
-Please note that all contributos are required to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+Please note that all contributos are required to abide by our Code of Conduct.
 
 ## Different Ways to Contribute
 
@@ -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`.
@@ -38,16 +38,17 @@ it is important to understand the structure of the code and the repository.
     These are organized in subdirectories according to what they test:
     see the "Setup" section below for more details.
 
--   Documentation is found in `doc/`, and its structure is described in [its README file](doc/README.md).
+-   Documentation is found in `doc/`, and its structure is described in its README file.
     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,74 @@
+# Manage plotly.py project.
+
+RUN = uv run
+PACKAGE_DIRS = _plotly_utils plotly
+CODE_DIRS = ${PACKAGE_DIRS} scripts
+EXAMPLE_SRC =  $(wildcard doc/python/*.md)
+EXAMPLE_DST = $(patsubst doc/python/%.md,pages/examples/%.md,${EXAMPLE_SRC})
+
+## commands: show available commands
+commands:
+	@grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':'
+
+## docs: rebuild documentation
+.PHONY: docs
+docs:
+	${RUN} mkdocs build
+
+## docs-lint: check documentation
+docs-lint:
+	${RUN} pydoclint ${PACKAGE_DIRS}
+
+## docs-tmp: rebuild documentation saving Markdown in ./tmp
+docs-tmp:
+	MKDOCS_TEMP_DIR=./docs_tmp ${RUN} mkdocs build
+
+## examples: generate Markdown for individual doc/python
+examples: ${EXAMPLE_DST}
+
+pages/examples/%.md: doc/python/%.md
+	@mkdir -p pages/examples
+	${RUN} bin/run_markdown.py --outdir pages/examples --inline --verbose 2 $<
+
+## examples-force: force complete rebuild of examples
+examples-force:
+	touch ${EXAMPLES_SRC}
+	make examples
+
+## format: reformat code
+format:
+	${RUN} ruff format ${CODE_DIRS}
+
+## generate: generate code
+generate:
+	${RUN} bin/generate_code.py --codedir plotly
+	${RUN} ruff format plotly
+
+## lint: check the code
+lint:
+	${RUN} ruff check ${CODE_DIRS}
+
+## test: run tests
+test:
+	${RUN} pytest tests
+
+## updatejs: update JavaScript bundle
+updatejs:
+	${RUN} 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
+	@rm -rf docs
+	@rm -rf pages/examples
+
+## 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).