-
Notifications
You must be signed in to change notification settings - Fork 635
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
Merge docs/developers into docs/website/. #15396
Conversation
This is awesome! I really like using the dialect reference, and having the developer docs on the website too sounds nice. (random thumbs up) |
Glad they're useful! One thing that I've been wanting that would help for the reference pages and some of the developer docs is MLIR syntax highlighting. https://squidfunk.github.io/mkdocs-material/reference/code-blocks/ has an overview of the tech needed for that (Pygments or something else) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice, thanks Scott for handling the docs and keep it high standards!
Fixes iree-org#15116. ![image](https://github.com/openxla/iree/assets/4010439/db4e0fe5-36cb-4cae-8597-6607493f774f) ## Notes for review | Location description | Preview URL | | --------- | -------------- | | source folder (GitHub markdown) | [`docs/website/docs/developers/` on my fork](https://github.com/ScottTodd/iree/tree/developer-docs-folder/docs/website/docs/developers) | | website (mkdocs site generator) | https://scotttodd.github.io/iree/developers | * I tried to split this change into multiple smaller PRs / reviewable commits, but the nature of moving so many files around and getting them integrated into the website made that tricky * I may have missed some URL renamings. mkdocs warns about broken links on the website itself, at least ## Overview This takes the existing [`/docs/developers/`](https://github.com/openxla/iree/tree/main/docs/developers) folder and merges it into [`docs/website/`](https://github.com/openxla/iree/tree/main/docs/website) for publishing on https://iree.dev/. The website has historically been primarily serving an ambiguous group of "users" (hoping to take a model authored in an ML framework and deploy it to some target). This broadens the scope of the website to also include developers (from established maintainers to new contributors). This change does a few things: * Moves existing pages across folders * Deletes some stale pages * Updates page style to match what the "mkdocs" site generator and "mkdocs material" framework use * Updates links across the project to use website URLs, relative links, or GitHub links as appropriate ## Detailed list of changes * Added "edit this page" buttons to all pages ![image](https://github.com/openxla/iree/assets/4010439/04660ff5-3612-4062-820b-ef82686aad80) * Merged `building_with_bazel_[linux, macos, windows]` into a single "Building with Bazel" page that uses content tabs ![image](https://github.com/openxla/iree/assets/4010439/2beedc02-79d5-4039-a847-d86c5d471ee0) * Renamed files so alphabetical sorting highlights the category that each file belongs in ![image](https://github.com/openxla/iree/assets/4010439/c5a732ad-82f3-468b-b942-26d7e9d3c4ae) * Renamed files from using underscores to using dashes (more natural for URLs) * Merged some "debugging integration test" pages and deleted outdated information (pointing at old TensorFlow code that no longer exists) * Moved "developer tips" from the top level "Guides" category into the "General development topics" subsection under this new top level "Developers" category * Applied lint and style fixes to all files (e.g. max line length, `Subsection capitalization` instead of `Subsection Capitalization`) * Merged "contributor tips" into "contributing" * Redirected or removed references to docs/developers/ (e.g. website 404 page pointed there as another place to look for docs) * Deleted "codegen passes", "hal driver features", and "dynamic shapes" design docs (all were stale) * Removed references to old processes (quirks based on supporting Google's downstream monorepo) ## Future work This PR is focused primarily on moving pages over and making minor changes where appropriate. More work is needed to refresh the content on several pages. The "developer docs" should be seen as a wiki of sorts, so the support expectations are lower, but outdated or missing documentation can be worse than no documentation in some respects. Known issues to follow up on: * The "Contributing" page should be updated, perhaps with a separate page for "Infrastructure" forked out * We have many "benchmarking" and "profiling" pages. That's great, but people shouldn't need to read all of the pages to be productive * The design docs are _very_ outdated. I removed a few of them, but we should figure out if the remaining ones are worth keeping around. New pages would be nice too * These pages could have icons and other style tweaks, e.g. the sidebar shows icons but it looks better if all pages list them: ![image](https://github.com/openxla/iree/assets/4010439/7efb0bbd-23aa-4b91-8ee3-4787d800a3fb) * mkdocs [material] supports showing revision dates on files. That would be useful for showing how fresh a file is, but files can be touched by refactorings and generated files don't have git information... need to think through that a bit
Fixes #15116.
Notes for review
docs/website/docs/developers/
on my forkOverview
This takes the existing
/docs/developers/
folder and merges it intodocs/website/
for publishing on https://iree.dev/.The website has historically been primarily serving an ambiguous group of "users" (hoping to take a model authored in an ML framework and deploy it to some target). This broadens the scope of the website to also include developers (from established maintainers to new contributors).
This change does a few things:
Detailed list of changes
building_with_bazel_[linux, macos, windows]
into a single "Building with Bazel" page that uses content tabsSubsection capitalization
instead ofSubsection Capitalization
)Future work
This PR is focused primarily on moving pages over and making minor changes where appropriate. More work is needed to refresh the content on several pages. The "developer docs" should be seen as a wiki of sorts, so the support expectations are lower, but outdated or missing documentation can be worse than no documentation in some respects.
Known issues to follow up on: