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.

[LiamConnors]

One of the tests is failing because this is missing. I think we can restore it for now and completely remove it once we take down the old docs

[LiamConnors]

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.

[LiamConnors]

Why is this change needed in codegen for docs?

[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)