Add --md flag to azpysdk apistub to generate api.md

[Copilot]

azpysdk apistub lacked the ability to produce a human-readable markdown rendering of the generated API token JSON. This adds an --md flag that, after successful JSON token generation, invokes Export-APIViewMarkdown.ps1 to produce api.md in the same output directory.

Changes

• azpysdk/apistub.py
  • Added --md (dest="generate_md") flag to register() — action="store_true", default False
  • After a successful apistub run, if --md is set, calls Export-APIViewMarkdown.ps1 via subprocess.run with -TokenJsonPath <package_name>_python.json and -OutputPath <out_token_path>
  • Errors from the PS1 invocation (including FileNotFoundError when pwsh is absent) are caught and logged without masking the original apistub success

Usage

azpysdk apistub . --md
# Produces: <out_token_path>/azure-<package>_python.json  (existing)
#           <out_token_path>/api.md                        (new)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• pypi.org
  • Triggering command: /home/REDACTED/work/azure-sdk-for-python/azure-sdk-for-python/.venv/bin/pip pip install black (dns block)
  • Triggering command: /home/REDACTED/work/azure-sdk-for-python/azure-sdk-for-python/.venv/bin/pip pip install black --quiet (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[azpysdk] Add --md flag to azpysdk apistub to generate api.md</issue_title>
<issue_description>### Description

Part of Azure/azure-sdk-tools#12851.

Add an --md flag to azpysdk apistub. When passed, the command will additionally run Export-APIViewMarkdown.ps1 on the generated JSON token file to produce api.md.

azpysdk apistub . --md

Potential Implementation

Changes to eng/tools/azure-sdk-tools/azpysdk/apistub.py:

1. Add --md flag (action="store_true", default False) in the register() method.
2. After successfully writing the JSON token file, if --md is set, invoke via subprocess:

   subprocess.run(
       ["pwsh", "eng/common/scripts/Export-APIViewMarkdown.ps1",
        "-TokenJsonPath", <json_file>, "-OutputPath", <out_dir>],
       check=True
   )

   If pwsh is not available, fail with a clear error.
3. Place api.md in the same output directory as the token file (under <dest-dir>/<package-name>/ if --dest-dir is provided).

Deliverables

• azpysdk apistub supports a new --md to create an api.md file, which is output to the same directory as the APIView token file.
• If pwsh is not available, the utility fails gracefully with a clear error message.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [azpysdk] Add --md flag to azpysdk apistub to generate api.md #45758

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.