Skip to content

docs: Update docs style to fit style guide - #982

Open
peterjunpark wants to merge 3 commits into
docs/setup-rtdfrom
docs-style
Open

docs: Update docs style to fit style guide#982
peterjunpark wants to merge 3 commits into
docs/setup-rtdfrom
docs-style

Conversation

@peterjunpark

Copy link
Copy Markdown

Motivation

Apply Google developer documentation style guide:

  • Use sentence case for headings
  • Use second person ("you") instead of passive or third person
  • Use present tense and active voice
  • Remove filler words and Latin abbreviations ("e.g." → "for example", "i.e." → "that is")
  • Remove "please", "simply", "easy", "just"
  • Use numbered lists for sequential steps
  • Use Oxford comma consistently

Technical Details

Test Plan

Test Result

Submission Checklist

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
Copilot AI lite review requested due to automatic review settings August 7, 2026 19:58
@peterjunpark peterjunpark changed the title Docs style docs: Update docs style to fit style guide Aug 7, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 thread docs/index.rst
Comment on lines +48 to +52
* :doc:`FlyDSL Python DSL <api/dsl>`

* :doc:`Compiler and pipeline <api/dsl>`

* :doc:`Prebuilt kernels <api/kernels>`
Comment thread docs/index.rst
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.
:::
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants