feat: converting documentation to mkdocs #5276

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down Expand Up		@@ -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
Expand Down

23 changes: 13 additions & 10 deletions CONTRIBUTING.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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

Expand All		@@ -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`.
Expand All		@@ -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.
Expand Down Expand Up		@@ -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
Expand All		@@ -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`.
Expand All		@@ -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/
		```

80 changes: 80 additions & 0 deletions Makefile

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,80 @@
	# 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})
	MKDOCS_TEMP_DIR = ./docs_tmp

	## 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:
	@rm -rf ${MKDOCS_TEMP_DIR}
	MKDOCS_TEMP_DIR=${MKDOCS_TEMP_DIR} ${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

	## examples-toc: generate YAML table of contents for examples
	examples-toc:
	@python bin/build_example_toc.py ${EXAMPLE_SRC}

	## 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

19 changes: 9 additions & 10 deletions README.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand All		@@ -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
Expand All		@@ -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
Expand All		@@ -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).

Expand Down

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Uh oh!

feat: converting documentation to mkdocs #5276

Are you sure you want to change the base?

feat: converting documentation to mkdocs #5276

Filter by extension

Uh oh!

Diff view

Diff view

Uh oh!

There are no files selected for viewing

Uh oh!