Documentation conversion into Mkdocs #5384
Open
+565,271
−447,688
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…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.
Add `plotly.express` docstrings
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.
Exclude code blocks that aren't run
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.
…ew' pages of each category.
…ved links and removed dash banner from the API Reference overview page.
…tyled the hamburger menu view.
…ve site and fixed image styling.
Update link text descriptions
…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
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Converted the plotly.py documentation build into Mkdocs
\\\\[i\\\\]\\\\[{i}\\\\]ensures that Mkdocs will correctly render this portion of the docstring into[i][i].plotly/plotly.py/README.mdand index pages are placed in each individual category of examples underOverview.