Merge docs/developers into docs/website/. (#15396)
Fixes https://github.com/openxla/iree/issues/15116.
## 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
* Merged `building_with_bazel_[linux, macos, windows]` into a single
"Building with Bazel" page that uses content tabs
* Renamed files so alphabetical sorting highlights the category that
each file belongs in
* 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:
* 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
diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml
index 4867083..7a746a5 100644
--- a/docs/website/mkdocs.yml
+++ b/docs/website/mkdocs.yml
@@ -2,6 +2,7 @@
site_url: https://iree.dev/
repo_url: https://github.com/openxla/iree
repo_name: openxla/iree
+edit_uri: blob/main/docs/website/docs/
theme:
name: material
@@ -9,6 +10,7 @@
logo_alt: IREE
icon:
repo: fontawesome/brands/github
+ edit: material/file-eye-outline
font:
text: Noto
code: Noto Sans Mono
@@ -18,6 +20,7 @@
custom_dir: overrides
features:
+ - content.action.edit # Link to view/edit documentation source on GitHub
- content.code.annotate # Allow inline annotations
- content.code.copy # Enable copy button
- content.tabs.link # Link content tabs across site (e.g. Windows/Linux)
@@ -136,8 +139,6 @@
- GPU - CUDA: "guides/deployment-configurations/gpu-cuda.md"
- GPU - ROCm: "guides/deployment-configurations/gpu-rocm.md"
- GPU - Metal: "guides/deployment-configurations/gpu-metal.md"
- - "Other topics":
- - Developer tips and tricks: "guides/developer-tips.md"
- "Reference":
- "reference/index.md"
- "API bindings":
@@ -165,6 +166,40 @@
- Glossary: "reference/glossary.md"
- Optimization options: "reference/optimization-options.md"
- Extensions: "reference/extensions.md"
+ - "Developers":
+ - "developers/index.md"
+ - "General development topics":
+ - "developers/general/contributing.md"
+ - "developers/general/developer-overview.md"
+ - "developers/general/developer-tips.md"
+ - "developers/general/release-management.md"
+ - "developers/general/testing-guide.md"
+ - "Building":
+ - "developers/building/bazel.md"
+ - "developers/building/emscripten.md"
+ - "developers/building/cmake-options-and-variables.md"
+ - "developers/building/cmake-with-ccache.md"
+ - "Debugging":
+ - "developers/debugging/android-with-lldb.md"
+ - "developers/debugging/compile-time-regressions.md"
+ - "developers/debugging/integration-tests.md"
+ - "developers/debugging/releases.md"
+ - "developers/debugging/sanitizers.md"
+ - "Performance":
+ - "developers/performance/benchmarking.md"
+ - "developers/performance/benchmark-suites.md"
+ - "developers/performance/profiling.md"
+ - "developers/performance/profiling-cpu-events.md"
+ - "developers/performance/profiling-gpu-vulkan.md"
+ - "developers/performance/profiling-with-tracy.md"
+ - "Design docs":
+ - "developers/design-docs/cuda-backend.md"
+ - "developers/design-docs/design-roadmap.md"
+ - "developers/design-docs/function-abi.md"
+ - "developers/design-docs/invocation-execution-model.md"
+ - "Other topics":
+ - "developers/usage-best-practices.md"
+ - "developers/vulkan-environment-setup.md"
- "Community":
- "community/index.md"
- "Blog":
@@ -219,3 +254,6 @@
# Some blog post names/paths changed when setting up the blog plugin
"community/blog/2021-07-19-tflite-tosa.md": "community/blog/posts/tflite-tosa.md"
"community/blog/2021-10-13-mmt4d.md": "community/blog/posts/mmt4d.md"
+
+ # "Developers" section was added
+ "guides/developer-tips.md": "developers/general/developer-tips.md"
