Fix links for nested types in generated docs #24584
Conversation
Signed-off-by: Jade Abraham <[email protected]>
Signed-off-by: Jade Abraham <[email protected]>
| @@ -0,0 +1 @@ | |||
| -o docs --no-html --save-sphinx docs | |||
There was a problem hiding this comment.
Why use --no-html if you're going to call sphinx-build with the html flag later?
There was a problem hiding this comment.
I was getting errors from sphinx when not using --no-html, which I think are related to using --save-sphinx to the same directory as -o. Since for this test the sphinx output is not needed, I can simplify this (and the prediff)
| for m in re.finditer(reference_pat, html_output): | ||
| # for each reference, check if the link exists | ||
| link = m.group(1) | ||
| if not re.search(f'<a class="headerlink" href="#{link}" title="Permalink to this definition">', html_output): |
There was a problem hiding this comment.
I don't know enough about html and css formatting, are "headerlink" and the field names something that can be relied on? Or could they change in newer versions of Sphinx/Read the Docs?
There was a problem hiding this comment.
There is a possibility it could change in a future version. Parsing html with a regex like this is fragile, as there is no guarantee on the order of the fields. And "headerlink" and "title=..." could change (although I doubt they would). But within our version of sphinx I am more confident that we can rely on this order and the contents.
Signed-off-by: Jade Abraham <[email protected]>
This PR pulls in a fix from sphinxcontrib-chapeldomain that fixes how links for nested types are rendered. This PR also adds a test for chpldoc to lock in the correct behavior.
See chapel-lang/sphinxcontrib-chapeldomain#90 for details of the fix
[Reviewed by @lydia-duncan]