Skip to content

Review fixes: MyST markup, language, and grammar#1

Open
rkratky wants to merge 1 commit into
pushkarnk:springai-basicfrom
rkratky:review/springai-basic
Open

Review fixes: MyST markup, language, and grammar#1
rkratky wants to merge 1 commit into
pushkarnk:springai-basicfrom
rkratky:review/springai-basic

Conversation

@rkratky

@rkratky rkratky commented Jul 15, 2026

Copy link
Copy Markdown

Summary

Review fixes for PR canonical#135 (Add a basic Spring AI tutorial).

Changes

MyST markup:

  • Added two blank lines above each heading (except the first)
  • Added one blank line above/below all code blocks, lists, admonitions, and images
  • Converted all terminal CLI commands to the {terminal} directive (sphinx-terminal)
  • Converted all code blocks to {code-block} directive with :caption: for file-named blocks
  • Converted log/error output blocks to {terminal} with :output-only:
  • Used {code-block} none for web UI Q&A examples

Language and grammar:

  • Reworded future tense to present simple ("We will use" -> "We use")
  • Reworded "you may" / "if" / conditionals to imperative form
  • Removed "please" from prose
  • Fixed "Initialzing" -> "Initializing"
  • Fixed "inference with it" -> "perform inference with it"
  • Removed "should" where it expressed uncertainty ("should be logged" -> "are logged")

Semantic markup:

  • Package names: {pkg}
  • File/directory names: {file}
  • Commands: {command}

Serial comma:

  • Added serial comma to lists of 3+ items
  • Did not apply to 2-item lists

Other:

  • Ordered lists use 1. for all items
  • No {gui} role available; used plain backticks for the beta channel name

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.

1 participant