[Feature] Add --language to doc fetch

.changeset/doc-fetch-language.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli': minor
+---
+
+Add `--language` to `doc fetch` to filter shopify.dev Markdown code examples to a single language.

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -3174,6 +3174,15 @@
       "description": "The following flags are available for the `doc fetch` command:",
       "isPublicDocs": true,
       "members": [
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/doc-fetch.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--language <value>",
+          "value": "string",
+          "description": "Filter code examples in the returned Markdown to this language. Supply the language of the app you are building so examples match your stack. Optional — if omitted, or if shopify.dev does not recognize the language for a given page, the document includes examples in every language.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_LANGUAGE"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/doc-fetch.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -3210,7 +3219,7 @@
           "environmentValue": "SHOPIFY_FLAG_VERBOSE"
         }
       ],
-      "value": "export interface docfetch {\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Write the document to this file path instead of printing it to stdout.\n   * @environment SHOPIFY_FLAG_OUTPUT\n   */\n  '--output <value>'?: string\n\n  /**\n   * The shopify.dev URL to fetch.\n   * @environment SHOPIFY_FLAG_URL\n   */\n  '--url <value>': string\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+      "value": "export interface docfetch {\n  /**\n   * Filter code examples in the returned Markdown to this language. Supply the language of the app you are building so examples match your stack. Optional — if omitted, or if shopify.dev does not recognize the language for a given page, the document includes examples in every language.\n   * @environment SHOPIFY_FLAG_LANGUAGE\n   */\n  '--language <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Write the document to this file path instead of printing it to stdout.\n   * @environment SHOPIFY_FLAG_OUTPUT\n   */\n  '--output <value>'?: string\n\n  /**\n   * The shopify.dev URL to fetch.\n   * @environment SHOPIFY_FLAG_URL\n   */\n  '--url <value>': string\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
     }
   },
   "docsearch": {

packages/cli/README.md

@@ -2134,13 +2134,21 @@ DESCRIPTION
 
 ## `shopify doc fetch`
 
-Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.
+Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. Pass `--language` for the language of the app you are building so code examples match your stack. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.
 
 ```
 USAGE
-  $ shopify doc fetch --url <value> [--no-color] [--output <value>] [--verbose]
+  $ shopify doc fetch --url <value> [--language
+    javascript|typescript|python|ruby|php|rust|curl|liquid|graphql|html] [--no-color] [--output <value>] [--verbose]
 
 FLAGS
+  --language=<option>
+      Filter code examples in the returned Markdown to this language. Supply the language of the app you are building so
+      examples match your stack. Optional — if omitted, or if shopify.dev does not recognize the language for a given
+      page, the document includes examples in every language.
+      [env: SHOPIFY_FLAG_LANGUAGE]
+      <options: javascript|typescript|python|ruby|php|rust|curl|liquid|graphql|html>
+
   --no-color
       Disable color output.
       [env: SHOPIFY_FLAG_NO_COLOR]
@@ -2160,13 +2168,18 @@ FLAGS
 DESCRIPTION
   Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this
   tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like
-  a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.
+  a centrally-served skill. Pass `--language` for the language of the app you are building so code examples match your
+  stack. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.
 
 EXAMPLES
   # fetch the Markdown version of a Shopify.dev page
 
     $ shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli
 
+  # filter code examples to the language of the app you are building
+
+    $ shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --language ruby
+
   # save the document to a file instead of printing it
 
     $ shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --output docs/shopify-cli.md

packages/cli/oclif.manifest.json

@@ -4738,13 +4738,34 @@
       ],
       "args": {
       },
-      "description": "Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.",
+      "description": "Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. Pass `--language` for the language of the app you are building so code examples match your stack. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.",
       "enableJsonFlag": false,
       "examples": [
         "# fetch the Markdown version of a Shopify.dev page\nshopify doc fetch --url https://shopify.dev/docs/api/shopify-cli",
+        "# filter code examples to the language of the app you are building\nshopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --language ruby",
         "# save the document to a file instead of printing it\nshopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --output docs/shopify-cli.md"
       ],
       "flags": {
+        "language": {
+          "description": "Filter code examples in the returned Markdown to this language. Supply the language of the app you are building so examples match your stack. Optional — if omitted, or if shopify.dev does not recognize the language for a given page, the document includes examples in every language.",
+          "env": "SHOPIFY_FLAG_LANGUAGE",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "language",
+          "options": [
+            "javascript",
+            "typescript",
+            "python",
+            "ruby",
+            "php",
+            "rust",
+            "curl",
+            "liquid",
+            "graphql",
+            "html"
+          ],
+          "type": "option"
+        },
         "no-color": {
           "allowNo": false,
           "description": "Disable color output.",

packages/cli/src/cli/commands/doc/fetch.ts

@@ -5,11 +5,13 @@ import {Flags} from '@oclif/core'
 
 export default class DocFetch extends Command {
   static description =
-    'Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.'
+    'Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. Pass `--language` for the language of the app you are building so code examples match your stack. For finding the relevant pieces of content across shopify.dev instead, use `doc search`.'
 
   static examples = [
     `# fetch the Markdown version of a Shopify.dev page
 shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli`,
+    `# filter code examples to the language of the app you are building
+shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --language ruby`,
     `# save the document to a file instead of printing it
 shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --output docs/shopify-cli.md`,
   ]
@@ -21,6 +23,12 @@ shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --output docs/s
       env: 'SHOPIFY_FLAG_URL',
       required: true,
     }),
+    language: Flags.string({
+      description:
+        'Filter code examples in the returned Markdown to this language. Supply the language of the app you are building so examples match your stack. Optional — if omitted, or if shopify.dev does not recognize the language for a given page, the document includes examples in every language.',
+      env: 'SHOPIFY_FLAG_LANGUAGE',
+      options: ['javascript', 'typescript', 'python', 'ruby', 'php', 'rust', 'curl', 'liquid', 'graphql', 'html'],
+    }),
     output: Flags.string({
       description: 'Write the document to this file path instead of printing it to stdout.',
       env: 'SHOPIFY_FLAG_OUTPUT',
@@ -29,6 +37,6 @@ shopify doc fetch --url https://shopify.dev/docs/api/shopify-cli --output docs/s
 
   async run(): Promise<void> {
     const {flags} = await this.parse(DocFetch)
-    await docFetchService(flags.url, flags.output)
+    await docFetchService(flags.url, flags.output, flags.language)
   }
 }

packages/cli/src/cli/services/commands/doc/fetch.test.ts

@@ -57,6 +57,14 @@ describe('docFetchService', () => {
     })
   })
 
+  test('sends Accept-Language when a language is provided', async () => {
+    await docFetchService('https://shopify.dev/docs/api/shopify-cli', undefined, 'ruby')
+
+    expect(fetch).toHaveBeenCalledWith('https://shopify.dev/docs/api/shopify-cli', {
+      headers: {Accept: 'text/markdown', 'X-Shopify-Surface': 'cli', 'Accept-Language': 'ruby'},
+    })
+  })
+
   test('throws when the response is not ok', async () => {
     vi.mocked(fetch).mockResolvedValue({ok: false, status: 404, statusText: 'Not Found'} as any)
 

packages/cli/src/cli/services/commands/doc/fetch.ts

@@ -17,7 +17,7 @@ const SURFACE = 'cli'
 // hostname is one of these or a subdomain of one of these.
 const ALLOWED_HOSTS = ['shopify.dev']
 
-export async function docFetchService(url: string, outputPath?: string) {
+export async function docFetchService(url: string, outputPath?: string, language?: string) {
   let parsedURL: URL
   try {
     parsedURL = new URL(url)
@@ -31,7 +31,16 @@ export async function docFetchService(url: string, outputPath?: string) {
     throw new AbortError(`Only documents from the following hosts can be fetched: ${ALLOWED_HOSTS.join(', ')}.`)
   }
 
-  const response = await fetch(url, {headers: {Accept: MARKDOWN_CONTENT_TYPE, [SURFACE_HEADER]: SURFACE}})
+  // shopify.dev filters Markdown code examples when Accept-Language is a
+  // recognized programming-language key. Unrecognized values are ignored and
+  // the unfiltered document is returned.
+  const response = await fetch(url, {
+    headers: {
+      Accept: MARKDOWN_CONTENT_TYPE,
+      [SURFACE_HEADER]: SURFACE,
+      ...(language ? {'Accept-Language': language} : {}),
+    },
+  })
 
   if (!response.ok) {
     throw new AbortError(`Failed to fetch ${url}: ${response.status} ${response.statusText}`)