Movatterモバイル変換


[0]ホーム

URL:


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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Open
daexs wants to merge191 commits intoplotly:live-docs
base:live-docs
Choose a base branch
Loading
fromdaexs:mkdocs-conversion

Conversation

@daexs
Copy link
Collaborator

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 isplotly/plotly.py/README.md and index pages are placed in each individual category of examples underOverview.

gvwilsonand others added30 commitsJuly 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 longerencounter '[][]' 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 longerencounter '[][]' 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.
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Could we update the readme to have the new doc build process.
And add a github action that runs all the commands required to build the docs and save them as an artifact.

Comment on lines +31 to +35
PROJECT_ROOT=Path(__file__).parent.parent.parent
PLOT_SCHEMA_RELATIVE=Path("resources")/"plot-schema.json"
PLOT_SCHEMA=PROJECT_ROOT/PLOT_SCHEMA_RELATIVE


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Why is this change needed in codegen for docs?

@daexsdaexs self-assigned thisNov 6, 2025
@daexsdaexs added featuresomething new P1needed for current cycle labelsNov 6, 2025
@emilykl
Copy link
Contributor

@LiamConnors@daexs Theperform_codegen() function is missing the reformat step.

See lines 326-330 ofcommands.py:Link

These lines should be added at the end ofperform_codegen() inbin/codegen/__init__.py.

There is also a missing import statement.import argparse should be added at the top ofbin/utils.py.

@emilykl
Copy link
Contributor

Actually, hmm. It looks like the entirereformat_code() function is missing from this branch entirely.

To be honest I'm not very enthusiastic about mixing codegen changes in with this PR. I realize there are some changes to the codegen which are required in order for Mkdocs to work properly, but I would prefer to keep the codegen changes toonly what is strictly necessary for the docs to work, and keep any other codegen changes for another PR.

@emilykl
Copy link
Contributor

In any case, thereformat_code() function is pretty minimal. It's just:

importsubprocess...defreformat_code(outdir):"""Reformat Python code using settings in pyproject.toml."""subprocess.call(["ruff","format",*make_paths(outdir)])

So the immediate issue can be fixed by adding that function tobin/utils.py.

@emilykl
Copy link
Contributor

emilykl commentedNov 7, 2025
edited
Loading

@daexs There are two changes I had to make in order to build the docs successfully on my machine:

  • Addimport argparse at the top ofbin/utils.py

  • Add--extra docs to thereference command in the Makefile, so that the final command is:${RUN} --extra docs bin/generate_graph_objects_docs.py (This tellsuv to run the command in an environment where thedocs requirements are installed)

@daexs
Copy link
CollaboratorAuthor

Actually, hmm. It looks like the entirereformat_code() function is missing from this branch entirely.

To be honest I'm not very enthusiastic about mixing codegen changes in with this PR. I realize there are some changes to the codegen which are required in order for Mkdocs to work properly, but I would prefer to keep the codegen changes toonly what is strictly necessary for the docs to work, and keep any other codegen changes for another PR.

@emilykl I tried adding the lines of code (functions, import statements) you mentioned were missing, but it ended up breaking the process of regenerating the code. I took a look at older commits and it seems like there was a lot of refactoring that was done to make the current codegen work. This is also causing thedev_build test to fail because the test expects acommands.py in the top level but it was refactored intobin/utils.py. I have left them as is in this PR for now because I tried to undo some things, but it created a larger mess. I will have to spend more time checking why each change was made.

If I understand correctly,reformat_code might have been deleted because the make rulemake generate runs the reformatting process with ruff right after the code is generated.

@emilykl
Copy link
Contributor

@daexs Yeah after looking at the history I realized all the codegen refactor was done by Greg, so don't worry about it!

Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment

Reviewers

@LiamConnorsLiamConnorsLiamConnors left review comments

@emilyklemilyklAwaiting requested review from emilykl

@camdecostercamdecosterAwaiting requested review from camdecoster

Assignees

@daexsdaexs

Labels

featuresomething newmkdocsP1needed for current cycle

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@daexs@emilykl@gvwilson@LiamConnors

[8]ページ先頭

©2009-2025 Movatter.jp