Skip to content

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

Open
rkratky wants to merge 1 commit into
pushkarnk:spring-ai-tool-callingfrom
rkratky:review/spring-ai-tool-calling
Open

Review fixes: MyST markup, language, and grammar#3
rkratky wants to merge 1 commit into
pushkarnk:spring-ai-tool-callingfrom
rkratky:review/spring-ai-tool-calling

Conversation

@rkratky

@rkratky rkratky commented Jul 15, 2026

Copy link
Copy Markdown

Summary

Review fixes for PR canonical#139 (Add a tutorial for tool-calling 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 log output blocks to {terminal} with :output-only:
  • Used {code-block} none for web UI Q&A examples
  • Indented all list item content (including code blocks, admonitions, and inter-item text) to align with 1. prefix

Language and grammar:

  • Reworded future tense to present simple ("We will augment" -> "We augment", "This tutorial will reuse" -> "This tutorial reuses", "we will use" -> "we use")
  • Reworded "you may" / "may be" / "if" / conditionals to imperative form
  • Fixed "dif ficult" -> "difficult"
  • Fixed "lets" -> "let's"
  • Removed "should" where expressing uncertainty ("should be seen" -> "is displayed", "should be expected" -> "is expected")

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
  • "This is not a full source listing of DemoChatService.java" kept (file name part of sentence, not a filename-only line)

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