docs: Update docs style to fit style guide - #982
Open
peterjunpark wants to merge 3 commits into
Open
Conversation
Format all docs listed in docs/sphinx/_toc.yml.in per the Google
Developer Documentation Style Guide:
- Sentence case for all headings
- Active voice and second-person ("you") throughout
- Present tense for descriptions and steps
- Spell out "e.g." → "for example", "i.e." → "that is"
- Spell out ampersands in headings and prose
- Convert sequential steps to numbered lists with terminal periods
Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
fix heading underline
fix
fix typo
docs: add license
fmt
Contributor
There was a problem hiding this comment.
Pull request overview
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Applies Google developer documentation style guidelines across FlyDSL docs and improves navigation structure.
Changes:
- Standardized heading casing and rewrote phrases to active voice / second person, removing Latin abbreviations and filler words.
- Reformatted lists and descriptions for consistency and clarity across multiple guides/tutorials.
- Added an “About → License” docs page and updated the docs TOC/navigation.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tutorials/kernel_development.rst | Sentence-case headings and “for example” wording updates to match style guide. |
| docs/tutorials/basic_usage.rst | Style-guide rewrites for headings and imperative phrasing. |
| docs/testing_benchmarking_guide.md | Rewrites intro text and normalizes heading casing. |
| docs/sphinx/_toc.yml.in | Adds “About” section and links to the new license page. |
| docs/quickstart.rst | Sentence-case headings and clearer installation pointer in the intro. |
| docs/prebuilt_kernels_guide.md | Normalizes headings/table labels and replaces Latin abbreviations. |
| docs/layout_system_guide.md | Rewrites lead-in text and heading casing; changes “Important” callout formatting. |
| docs/language/arithmetic_types.md | Sentence-case headings and rephrased explanations for clarity. |
| docs/kernel_tuning_guide.md | Sentence-case headings and active-voice rewrites. |
| docs/kernel_authoring_guide.md | Sentence-case headings and style-guide rewrites throughout. |
| docs/installation.rst | Renames top heading, adds intro, and improves verification instructions. |
| docs/index.rst | Adds a card/grid-based landing page navigation structure. |
| docs/extern_integration_guide.md | Replaces Latin abbreviations and cleans up spacing/phrasing. |
| docs/cute_layout_algebra_guide.md | Sentence-case headings and consistent terminology/casing. |
| docs/autotune_guide.md | Fixes phrasing and removes filler; improves readability of failure behavior section. |
| docs/architecture_guide.md | Sentence-case headings and rewrites lists into consistent, punctuated steps. |
| docs/api_stability.md | Shifts phrasing toward second person and active voice. |
| docs/api/kernels.rst | Sentence-case headings for API reference page. |
| docs/api/dsl.rst | Sentence-case section headings and removes Latin abbreviations in examples. |
| docs/api/compiler.rst | Renames headings to sentence case (“and” instead of “&”) and normalizes list casing. |
| docs/about/license.rst | Adds a license page that includes the repository LICENSE file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+48
to
+52
| * :doc:`FlyDSL Python DSL <api/dsl>` | ||
|
|
||
| * :doc:`Compiler and pipeline <api/dsl>` | ||
|
|
||
| * :doc:`Prebuilt kernels <api/kernels>` |
Comment on lines
+13
to
+22
| .. grid:: 1 1 2 2 | ||
| :gutter: 3 | ||
|
|
||
| .. grid-item-card:: Getting started | ||
|
|
||
| * :doc:`Install FlyDSL <installation>` | ||
|
|
||
| * :doc:`Quick start <quickstart>` | ||
|
|
||
| * :doc:`API stability <api_stability>` |
Comment on lines
+5
to
+7
| :::{important} | ||
| All `fx.*` layout operations generate MLIR IR and must be called inside a `@flyc.kernel` or `@flyc.jit` function body. The code snippets below show API usage patterns within that context, not standalone scripts. | ||
| ::: |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Motivation
Apply Google developer documentation style guide:
Technical Details
Test Plan
Test Result
Submission Checklist