-
-
Couldn't load subscription status.
- Fork 2.7k
feat: converting documentation to mkdocs #5276
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
Draft
Draft
+579,534
−441,279
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
@gvwilson
gvwilson
added
feature
something new
P1
needed for current cycle
documentation
written for humans
labels
Jul 10, 2025
@gvwilson
gvwilson
force-pushed
the
mkdocs-conversion
branch
2 times, most recently
from
July 15, 2025 17:54
6c0e2ec to
72e0aef
Compare
2 tasks
@gvwilson
gvwilson
force-pushed
the
mkdocs-conversion
branch
2 times, most recently
from
July 17, 2025 13:25
8011f8f to
4e10f11
Compare
...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.
@gvwilson
gvwilson
force-pushed
the
mkdocs-conversion
branch
from
July 17, 2025 13:30
4e10f11 to
a2787a0
Compare
Add `plotly.express` docstrings
preload _plotly_utils to display full reference content for plotly.colors
@gvwilson
gvwilson
force-pushed
the
mkdocs-conversion
branch
from
July 25, 2025 15:31
8e7ecf8 to
347ad20
Compare
- 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.
@gvwilson
gvwilson
force-pushed
the
mkdocs-conversion
branch
from
July 25, 2025 15:31
347ad20 to
9525f6a
Compare
- 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.
feat: allow `--schema path` option to code generation
@gvwilson
gvwilson
force-pushed
the
mkdocs-conversion
branch
from
August 29, 2025 20:22
6e35841 to
8607d4a
Compare
...tarted.md' to the ToC.
...fixes to imports/variables missing in subsequent code blocks.
...IL's Image.show()
- Filter out `_something` files in `plotly/graph_objects`. - Move their content to `something`. - General refactoring of `bin/generate_references_pages.py` to be more readable. TODO: get the class name like `Bar` into the ToC rather than `plotly.graph_objects.bar`.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Uh oh!
There was an error while loading. Please reload this page.
Paired with plotly/plotly.js#7469 (formatting changes to JavaScript that Python docs are derived from).
commands.pyto scripts in newbindirectory and breakinto individual scripts.
./codegento./bin/codegen.plot-schema.jsonto./resourcesrather than burying it under thecodegenfolder.Makefileto run commands instead of putting everything incommands.py.ruffdirectly for checking and formatting rather than launching asubprocess from Python as
commands.pydid..gitignore to ignoredocsanddocs_tmp. (Will eventually want to includedocsor overwritedoc`.)README.md.CONTRIBUTING.mdto describe relocation of commands and codegeneration to
bin.CONTRIBUTING.mddocuments--local,--devrepoand--devbranchoptionsfor updating JavaScript bundle that
commands.pydidn't seem to provide.mkdocs.ymlconfiguration file formkdocs.mkdocsdoes not support reading configuration frompyproject.toml, sowe need the extra config file.
materialtheme.pagesand write output todocs.mkdocs-gen-filesplugin.(See discussion of
bin/generate_reference_pages.pybelow.)google(even though much of our documentationisn't formatted that way).
pagesthat include files from the rootdirectory (README, code of conduct, contributors' guide, license).
the content is transcluded one directory lower.
plotly/_subplots.pyto escape closing]with backslashto avoid confusing
mkdocsMarkdown.\\]because we need\]in theactual string. We could convert the docstrings to literal strings prefixed
with
rto avoid the double backslash.[as\\[for the same reason.plotly/basedatatypes.py.plotly/express/_core.py.pyproject.tomlto installmkdocsand related packages for dev.pyproject.tomlto installpydoclintfor checking documentation.uv.lockto match.To do:
scripts/gen_ref_pages.pyintocommands.py. (Can't do this becausemkdocs.ymlonly accepts the name of the script, not parameters.)mkdocs.pydoclint..mdfiles in root directory (taken out because they don't resolve when those files are transcluded frompages/*.md).\[formatting glitch in the following files (caused by replacing][with]\[to avoid Markdown thinking it's a reference link, but the text is inside back quotes):