Re: [PR] Link registry modules to the guide section that documents them [airflow]

["kaxil (via GitHub)" <gi...@apache.org>]

kaxil commented on PR #71477:
URL: https://github.com/apache/airflow/pull/71477#issuecomment-5922390825

   Round-2 items all landed, thanks. The two title shapes resolve 31 names in common.ai and the anchors match docutils' ids. One wrong link and a few smaller things, none blocking.
   
   **`SandboxToolset` lands on a parameter table.** `sandbox/configuration.rst:432` is titled ``` ``SandboxToolset`` parameters ```, and the leading shape accepts it because the run doesn't need to reach the end of the title. No page title names the class, so it resolves to `sandbox/configuration.html#sandboxtoolset-parameters` (at 0.10.0 as well) rather than the sandbox guide. Retitling `sandbox/index.rst` to ``` Sandboxed execution for agents: ``SandboxToolset`` ``` fixes it with no code change, since a page title wins. Anchoring `_LEADING_LITERAL_NAME_RUN` at `\s*$` would close the general case: over every provider at HEAD, and at common.ai 0.8.0 and 0.10.0, the only resolution that changes is this one, because `MCPHook`, `@task.snowpark` and the informatica option names are bare titles.
   
   **Anchors come from the working tree, URLs from `/stable`.** On a release publish `checkout-ref` makes those agree. A `workflow_dispatch` build from main, or a full build from another provider's ref, can emit a fragment (or after a page rename, a page) that stable doesn't have yet. Class discovery already reads the same tree, so this isn't new, but when `version` is set the docs could come from `providers-{id}/{version}` through the same ls-tree + cat-file reader `extract_versions.py` uses. Fine as a follow-up.
   
   Tests and nits:
   - Nothing covers the `.endswith(".rst")` filter in `extract_versions.read_guide_docs`: every fixture lists only `.rst` paths. The docs trees carry pngs, svgs and `conf.py`, and one of those reaching `git_cat_file_batch` raises on the UTF-8 decode. Adding a png and a `conf.py` path to the fixture in `test_skips_generated_and_release_note_pages_before_calling_git_show` would pin it, and that test name should say the batch read rather than `git_show`.
   - "A leading name beats a trailing one" holds (``` ``A``: ``B`` ``` gives `['A']`) but no test fails if the two regexes are swapped in `_extract_names_from_title`.
   - The `git_cat_file_batch` docstring says `git_show` fails loud on `CalledProcessError`, but `git_show` catches it and returns `None`. That last clause can go.
   - `test_docs_guides.py:125` cites #73523 and `:219` calls it "the reviewer-reported case". Describing the title shape there reads better than a PR reference.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org