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

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
gvwilson wants to merge 71 commits into main
base: main
Choose a base branch
Loading
from mkdocs-conversion
Draft

Conversation

@gvwilson
Copy link
Contributor

@gvwilson gvwilson commented Jul 10, 2025
edited
Loading

Paired with plotly/plotly.js#7469 (formatting changes to JavaScript that Python docs are derived from).

  • Move contents of commands.py to scripts in new bin directory and 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 docsanddocs_tmp. (Will eventually want to include docsor overwritedoc`.)
  • 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.

To do:

  • Move scripts/gen_ref_pages.py into commands.py. (Can't do this because mkdocs.yml only accepts the name of the script, not parameters.)
  • Include content from docstrings in hand-written Python code.
  • Include content from docstrings in generated Python code.
  • Include navigation links in left nav bar.
  • Clean up warnings produced by mkdocs.
  • Add linting for docstring style.
  • Clean up (many) errors reported by pydoclint.
  • Re-introduce links between .md files in root directory (taken out because they don't resolve when those files are transcluded from pages/*.md).
  • Fix \[ 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):
    • plotly/graph_objs/histogram2dcontour/_contours/index.html
    • plotly/graph_objs/contour/_contours/index.html
    • plotly/graph_objs/contourcarpet/_contours/index.html
    • plotly/graph_objs/table/_header/index.html
    • plotly/graph_objs/table/_cells/index.html

@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 6c0e2ec to 72e0aef Compare July 15, 2025 17:54
...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 `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.
daexs and others added 16 commits August 20, 2025 15:06
feat: allow `--schema path` option to code generation
daexs and others added 13 commits September 2, 2025 11:02
...fixes to imports/variables missing in subsequent code blocks.
- 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

Reviewers

@LiamConnors LiamConnors Awaiting requested review from LiamConnors

At least 1 approving review is required to merge this pull request.

Labels

documentation written for humans feature something new P1 needed for current cycle

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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