gapic-generator-python icon indicating copy to clipboard operation
gapic-generator-python copied to clipboard
verified publisher icon googleapis

optimize rst

Open ohmayr opened this issue 1 month ago • 1 comments

This PR optimizes gapic/utils/rst.py to use native Python regex for the majority of docstring conversions (Markdown to RST), resolving a major performance bottleneck caused by shelling out to pandoc. pypandoc is retained only as a fallback for complex tables.

Performance Impact: Reduces generation time per API from ~52s to ~10s (for google-cloud-discoveryengine).

Explanation of Diffs This PR introduces a large number of docstring changes. These are expected and acceptable for the following reasons:

  • Text Reflow (Cosmetic): We switched from Pandoc's text wrapping algorithm to Python's textwrap. This causes line breaks to shift, but the content remains semantically identical.

  • Link Fixes (Corrective): Reference-style links (e.g., [Message][pkg.Message]) were previously ignored by Pandoc and rendered as plain text. This change correctly converts them into valid RST hyperlinks.

  • List Markers (Cosmetic): The script now preserves the original * list bullets used in the source protos, whereas Pandoc normalized them to -.

ohmayr avatar Dec 09 '25 12:12 ohmayr