Documentation conversion into Mkdocs

[daexs]

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.

[emilykl]

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

See lines 326-330 of commands.py: Link

These lines should be added at the end of perform_codegen() in bin/codegen/__init__.py.

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

[emilykl]

Actually, hmm. It looks like the entire reformat_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 to only what is strictly necessary for the docs to work, and keep any other codegen changes for another PR.

[emilykl]

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

import subprocess

...

def reformat_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 to bin/utils.py.

[emilykl]

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

• Add import argparse at the top of bin/utils.py

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

[daexs]

Actually, hmm. It looks like the entire reformat_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 to only 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 the dev_build test to fail because the test expects a commands.py in the top level but it was refactored into bin/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 rule make generate runs the reformatting process with ruff right after the code is generated.

[emilykl]

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