Skip to content

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

Open
rkratky wants to merge 1 commit into
pushkarnk:springai-ragfrom
rkratky:review/springai-rag
Open

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

Conversation

@rkratky

@rkratky rkratky commented Jul 15, 2026

Copy link
Copy Markdown

Summary

Review fixes for PR canonical#136 (Add a tutorial for implementing RAG with Spring AI).

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 error message blocks to {terminal} with :output-only:
  • Removed __File__: lines (captions now carry filenames)
  • Heading anchor (unblocking-opensearch)= placed directly above heading
  • Replaced "section 1.4.4" with {ref}unblocking-opensearch``

Language and grammar:

  • Reworded future tense to present simple ("This tutorial will use" -> "This tutorial uses", "will show" -> "shows")
  • Reworded "you may" / "may be" / "if" / conditionals to imperative form
  • Removed "please" from prose
  • Fixed "lets" -> "let's" (2x)
  • Fixed "Please give process this" -> "Give this process"
  • Fixed "OpenSource" -> "OpenSearch"
  • Fixed "is you don't" -> "(skip when already installed)"
  • Removed "should" / "would" where expressing uncertainty ("should launch" -> "launches", "should unblock" -> "unblocks", "would reset" -> "resets")

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

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