Fix mkdocs autoref links to use reference-style syntax - #184
Fix mkdocs autoref links to use reference-style syntax#184Mustaphayinka wants to merge 2 commits into
Conversation
|
Nice, thank you @Mustaphayinka. For acceptance testing, would you be able to confirm that the new links bring us to the desired targets? I would usually ask for a screenshot for docs related updates but I realize that might not be the most appropriate for checking link targets. As an aside - I wonder if there is a GitHub actions workflow we can set up to check for broken links in the docs and make sure they all resolve. Maybe we can create a new issue to add that check! I see the CI build is currently failing, but due to line too long errors. We can try adding a pylint disable comment (on the tail / closing end of the docstring triple quotes should work I believe). |
|
Fixed both issues: corrected line-too-long errors by wrapping each affected docstring with scoped pylint disable/enable comments. For acceptance testing, I built the documentation locally with mkdocs build and inspected the generated HTML directly. The autorefs links now resolve as expected, with class="autorefs autorefs-internal" and matching href/anchor pairs; I did not rely on screenshots of a browser session. This also exposed and allowed me to fix a genuine case-mismatch bug: the docstring for calculateifainv linked to netradiativeheatfluxfunctionofT with a capital T, while the actual function is netradiativeheatfluxfunctionoft with a lowercase t. Once the syntax was corrected, autorefs properly identified the link as an unresolved cross-reference something the previously broken syntax had been masking. |
| See corresponding documentation below for more information about each. | ||
| """ | ||
| return np.load(self.data_filepath) | ||
|
|
There was a problem hiding this comment.
Let's add this new line back please
| def reward_info_value_matrix(self) -> np.ndarray: | ||
| """Time series reward information data.""" | ||
| return self.data["reward_info_value_matrix"] | ||
|
|
There was a problem hiding this comment.
let's add this new line back please
| For example: | ||
|
|
||
| ```py | ||
| ```py |
There was a problem hiding this comment.
I would like for docstring content to be nested inside the docstring (in terms of tabs and spaces), not on the left margin, if we can help it.
| def building_dirpath(self): | ||
| """The local directory containing the building's dataset, after it has been | ||
| extracted from the local zip file. | ||
| """ |
There was a problem hiding this comment.
For all of these line too long disable comments, I believe we could just do a single comment to the right of the end of the docstring, like:
"""
This is the docstring content....................................
""" # pylint: disable=line-too-long
could you please try this out for all instances of the comment
| # pylint: disable=line-too-long | ||
| # pylint: disable=line-too-long | ||
| # pylint: disable=line-too-long | ||
| # pylint: disable=line-too-long |
There was a problem hiding this comment.
Let's remove duplicate comments please
| IFA_inv : The IFA inverse matrix. | ||
| """ | ||
| # pylint: enable=line-too-long | ||
| # pylint: enable=line-too-long |
There was a problem hiding this comment.
let's remove duplicate comments please. these don't nest
|
@Mustaphayinka thanks for the follow up. I just left some minor comments about formatting. Please address, and then we can get this merged. Thank you! Also, yes please open a new issue for that supply chain issue you mentioned. |
|
Thanks for the feedback. I will address all of these, moving the pylint comments inline, fixing the indentation in the code blocks, removing the duplicate comments, and adding back the blank lines. |
2 participants
Fixes #107
In dataset.py, partition.py, and buildingradiationutils.py, the docstrings used standard Markdown relative links (text). MkDocs’ link resolver could not interpret them, which produced the “unrecognized relative link” warning mentioned in the issue. They still resolved through mkdocstrings/autorefs, but only incidentally.
Changed all 23 instances to reference-style links ([text][anchor]), the syntax autorefs is designed to intercept and resolve against the anchors generated by mkdocstrings. This should suppress the warning and allow the links to resolve reliably instead of working around a bug in the resolution path and also verified no remaining instances of the old pattern across all three affected files.