Skip to content
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

Merged
merged 16 commits into from
Nov 3, 2023

Conversation

ScottTodd
Copy link
Member

@ScottTodd ScottTodd commented Nov 2, 2023

Fixes #15116.

image

Notes for review

Location description Preview URL
source folder (GitHub markdown) docs/website/docs/developers/ on my fork
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/ folder and merges it into 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
  • Merged building_with_bazel_[linux, macos, windows] into a single "Building with Bazel" page that uses content tabs
    image
  • Renamed files so alphabetical sorting highlights the category that each file belongs in
    image
  • 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
  • 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

@ScottTodd ScottTodd added the documentation ✏️ Improvements or additions to documentation label Nov 2, 2023
@qedawkins
Copy link
Contributor

This is awesome! I really like using the dialect reference, and having the developer docs on the website too sounds nice. (random thumbs up)

@ScottTodd
Copy link
Member Author

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)

@ScottTodd ScottTodd requested a review from antiagainst November 2, 2023 23:07
Copy link
Contributor

@antiagainst antiagainst left a 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!

@ScottTodd ScottTodd merged commit 573f5e9 into iree-org:main Nov 3, 2023
57 checks passed
@ScottTodd ScottTodd deleted the developer-docs-folder branch November 3, 2023 15:31
ramiro050 pushed a commit to ramiro050/iree that referenced this pull request Dec 19, 2023
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation ✏️ Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add "Developers" section to website
4 participants