Documentation conversion into Mkdocs #7609
Open
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
…ocs-conversion
- Import Jekyll material from graphic-library-docs repository. - Remove (most) mentions of languages other than Python and JavaScript. - Add Makefile to re-run commands.
… into mkdocs-conversion
…nto mkdocs-conversion
…the html snippets for each file under 'docs/tmp/'
…om the 'mkdocs.yml' file.
- Add `./Makefile` with commands to rebuild documentation using the
commands shown below. (We'll tidy this up in the final step.)
- `make examples`
- `make reference`
- `make build`
- Move scripts from `./docs/bin` to `./bin` and adjust paths in
scripts as needed to pick up the right files and to build into
`./tmp`.
- Modify `./mkdocs.yml` to build from `./tmp`.
- Modify `./.gitignore` to ignore `./tmp`.
Note that this is only a step toward the final cleaned-up version: the
next step is to move `./docs/_posts` into the root directory, then
remove `./docs` entirely and build the site into `./docs` rather than
into `./doc`.
refactor: move documentation generation into the root directory
- and remove last vestiges of Jekyll
…into mkdocs-conversion
LiamConnors
reviewed
Nov 6, 2025
docs/CONTRIBUTING.md
Outdated
Comment on lines
5
to
6
| Our JavaScript tutorials are written in HTML files in the `_posts/plotly_js` directory of this repository. | ||
|
|
Member
There was a problem hiding this comment.
Is this accurate? I don't see that directory
LiamConnors
reviewed
Nov 6, 2025
docs/CONTRIBUTING.md
Outdated
Comment on lines
9
to
15
| To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest. This can be done using the GitHub graphical user interface at https://github.com/plotly/graphing-library-docs. | ||
|
|
||
| The easiest way to do this is to follow the `Edit this page on GitHub` link at the top right of the page you are interested in contributing to: | ||
|
|
||
|  | ||
|
|
||
| **You don't have to worry about breaking the site when you submit a pull request!** This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request in order to ensure that it definitely increases the health of Plotly's graphing libraries codebase. |
Member
There was a problem hiding this comment.
This readme should be updated to have the new steps
LiamConnors
reviewed
Nov 6, 2025
LiamConnors
reviewed
Nov 6, 2025
LiamConnors
reviewed
Nov 6, 2025
LiamConnors
reviewed
Nov 6, 2025
Comment on lines
1
to
29
| # Manage plotly.js documentation. | ||
|
|
||
| RUN = uv run | ||
| SCHEMA_SRC = test/plot-schema.json | ||
| HANDWRITTEN = content | ||
| TMP = tmp | ||
|
|
||
| EXAMPLES_DIR = ${HANDWRITTEN}/plotly_js | ||
| EXAMPLES_IN := $(shell find "${EXAMPLES_DIR}" -name '*.html') | ||
| EXAMPLES_TMP = ${TMP}/javascript | ||
| EXAMPLES_OUT = ${EXAMPLES_TMP}/axes/index.html # could be any of the generated files | ||
|
|
||
| REFERENCE_DIR = ${HANDWRITTEN}/reference_pages/javascript/ | ||
| REFERENCE_IN := $(wildcard ${REFERENCE_DIR}/*.html) | ||
| REFERENCE_TMP = ${TMP}/reference | ||
| REFERENCE_OUT = ${REFERENCE_TMP}/bar/index.html # could be any of the generated files | ||
|
|
||
| DOCS_DIR=docs | ||
| DOCS_OUT=${DOCS_DIR}/sitemap.xml | ||
|
|
||
| ## commands: show available commands | ||
| commands: | ||
| @grep -h -E '^##' ${MAKEFILE_LIST} | sed -e 's/## //g' | column -t -s ':' | ||
|
|
||
| ## docs: rebuild full documentation in `./docs` | ||
| .PHONY: docs | ||
| docs: ${DOCS_OUT} | ||
|
|
||
| ${DOCS_OUT}: ${EXAMPLES_OUT} ${REFERENCE_OUT} |
Member
There was a problem hiding this comment.
Could we add to the docs contributing guide on how to build the docs, and maybe a GitHub action that runs the required steps to test generating the output.
LiamConnors
reviewed
Nov 6, 2025
Contributor
|
General comment on file organization: I'd like to minimize the number of files added at the top level of this repo. Ideally anything related to the docs should be contained inside a |
emilykl
reviewed
Nov 6, 2025
camdecoster
reviewed
Nov 7, 2025
Contributor
There was a problem hiding this comment.
We'll need to verify how things conclude with regard to the R library before removing these references.
Contributor
There was a problem hiding this comment.
Should we include versions for these packages?
Co-authored-by: Cameron DeCoster <cameron.decoster@gmail.com>
Co-authored-by: Cameron DeCoster <cameron.decoster@gmail.com>
…ed old instructions from the old build.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
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.
Converted the plotly.js documentation build into Mkdocs
src/traces/image/attributes.jsfor proper Markdown rendering on plotly.py docs' function docstrings.code-highlight.cssapplies syntax highlighting. This is done because the markdown files are HTML snippets.plotly/plotly.js/README.mdand index pages are placed in each individual category of examples underOverview.