Skip to content

Navigation Menu

Sign in
Appearance settings

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

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Documentation conversion into Mkdocs #5384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
daexs wants to merge 173 commits into plotly:live-docs
base: live-docs
Choose a base branch
Loading
from daexs:mkdocs-conversion

Conversation

@daexs
Copy link
Collaborator

@daexs daexs commented Oct 28, 2025

Converted the plotly.py documentation build into Mkdocs

  • Create a Mkdocs build for the plotly.py docs and reference pages, including styling.
  • Modifies the code generator to create output that is compatible with Markdown rendering. For example, \\\\[i\\\\]\\\\[{i}\\\\] ensures that Mkdocs will correctly render this portion of the docstring into [i][i].
  • Modifies the examples for any code block errors, jupyter special commands, and formatting issues. For example, lists do not render correctly unless a new line was added.
  • Modifies link references within example and reference pages for readability and converted url links into internal markdown links for Mkdocs to handle.
  • Home/Landing page is plotly/plotly.py/README.md and index pages are placed in each individual category of examples under Overview.

gvwilson and others added 30 commits July 17, 2025 09:30
...d break
 into individual scripts.
 - Tidy up imports etc. while doing so.
- Move code generation from `./codegen` to `./bin/codegen`.
- Move `plot-schema.json` to `./resources` rather than burying it under the
 `codegen` folder.
- Add `Makefile` to run commands instead of putting everything in `commands.py`.
 - Run `ruff` directly for checking and formatting rather than launching a
 subprocess from Python as `commands.py` did.
- Modify `.gitignore to ignore `docs` and `docs_tmp`. (Will eventually want to
 include `docs` or overwrite `doc`.)
- Minor reformatting of `README.md`.
- Update `CONTRIBUTING.md` to describe relocation of commands and code
 generation to `bin`.
 - `CONTRIBUTING.md` documents `--local`, `--devrepo` and `--devbranch` options
 for updating JavaScript bundle that `commands.py` didn't seem to provide.
- Add `mkdocs.yml` configuration file for `mkdocs`.
 - Most of this file was vibe coded using Claude.
 - `mkdocs` does not support reading configuration from `pyproject.toml`, so
 we need the extra config file.
 - Use `material` theme.
 - Read hand-written Markdown from `pages` and write output to `docs`.
 - Generate module index pages on the fly using `mkdocs-gen-files` plugin.
 (See discussion of `bin/generate_reference_pages.py` below.)
 - Set docstring style to `google` (even though much of our documentation
 isn't formatted that way).
- Add placeholder Markdown files in `pages` that include files from the root
 directory (README, code of conduct, contributors' guide, license).
 - Remove relative links between these pages because they don't work when
 the content is transcluded one directory lower.
- Modify docstring in `plotly/_subplots.py` to escape closing `]` with backslash
 to avoid confusing `mkdocs` Markdown.
 - Here and elsewhere the escape is written `\\]` because we need `\]` in the
 actual string. We could convert the docstrings to literal strings prefixed
 with `r` to avoid the double backslash.
 - Have also escaped some `[` as `\\[` for the same reason.
- Similar change to `plotly/basedatatypes.py`.
- Reformat line breaks in docstrings in `plotly/express/_core.py`.
- Modify `pyproject.toml` to install `mkdocs` and related packages for dev.
- Modify `pyproject.toml` to install `pydoclint` for checking documentation.
 - Currently reporting a *lot* of errors.
- Update `uv.lock` to match.
preload _plotly_utils to display full reference content for plotly.colors
- Add `bin/run_markdown.py` (with help from Claude).
 - Runs Python chunks embedded in Markdown, writing result as Markdown.
 - Has option to embed interactive figures as well as generate PNG.
- Modify `Makefile` to run the script on selected files for testing purposes.
 - Commented-out target runs on all.
To do:
- [ ] Figure out why `bin/run_markdown.py` fails with "too many open files" for large numbers of input files.
- [ ] Modify `Makefile` to allow select re-running as well as batch runs.
- [ ] Modify `bin/run_markdown.py` to use a single Kaleido sub-process to speed up image generation.
- Updates `pyproject.toml` to install packages previously listed in `doc/requirements.txt`.
- Removes `doc/requirements.txt`.
- Run `python bin/check-all-md.py doc/python/*.md` to re-run all examples.
Changes were made to line 2037, in the case where a node is valType info_array in the JSON with dimension: 2 (eg. groups in _node.py line 137).
This fixes the issue where markdown interprets it as a hyperlink. This line adds '[][]' to the description after the description passed in the JSON file as part of the validation process.
Now, markdown correctly interprets the brackets as consecutive brackets instead.
All three cases in 'InfoArrayValidator' no longer
encounter '[][]' errors. For examples, see
'_node.py' groups property, '_image.py' zmax property,
'_dimension.py' constraintrange property.
Keep the newline between "...specified as"
and "* ..." to avoid rendering a code block.
Note: Python now raises a SyntaxWarning due to '\['.
Changes were made to line 2037, in the case where a node is valType info_array in the JSON with dimension: 2 (eg. groups in _node.py line 137).
This fixes the issue where markdown interprets it as a hyperlink. This line adds '[][]' to the description after the description passed in the JSON file as part of the validation process.
Now, markdown correctly interprets the brackets as consecutive brackets instead.
All three cases in 'InfoArrayValidator' no longer
encounter '[][]' errors. For examples, see
'_node.py' groups property, '_image.py' zmax property,
'_dimension.py' constraintrange property.
Keep the newline between "...specified as"
and "* ..." to avoid rendering a code block.
Note: Python now raises a SyntaxWarning due to '\['.
For examples, see '_annotation.py' property axref.
daexs and others added 26 commits October 16, 2025 17:06
...ved links and removed dash banner from the API Reference overview page.
...n 'Visualizing Biological Data' section to match live site, and add SEO meta tags
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@LiamConnors LiamConnors Awaiting requested review from LiamConnors

Assignees

No one assigned

Labels

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /