Replace bare link with markdown-style link to appease downstream Hugo/Vale linting #687
Conversation
|
I am a public member of @viamrobotics , not sure why that test is failing 🤷 |
| @@ -79,8 +79,8 @@ message GetPointCloudMapResponse { | |||
| // format where XY is the ground plane and positive Z is up, following | |||
| // the Right Hand Rule. | |||
| // | |||
| // Read more about the pointcloud format here: | |||
| // https://pointclouds.org/documentation/tutorials/pcd_file_format.html | |||
There was a problem hiding this comment.
only thought is if we should use something else besides "in the docs" since the link doesn't go to our docs. maybe "in the pcd file documentation"?
There was a problem hiding this comment.
I'm fine with that, and actually originally wrote it that way. But that exceeds the 80 character limit that this file otherwise respects, and if I split up the markdown link between two separate lines, I'm afraid it'll wind up getting broken downstream since the PYI files preserve whitespace by inserting manual (double) newlines directly into their docstrings.
Choose a door, @JohnN193 :
a) violate the 80 character limit?
b) risk a broken link downstream that is both ugly and doesn't fix the issue?
c) leave my admittedly sparse link text?
Far downstream, the Viam docs ingest the Python SDK's docstrings into markdown.
The Python SDK ingests these .proto files and generates .pyi files with docstrings based on the comments here.
Our linter strongly dislikes bare links, breaking the docs build with an error if even one appears in our source markdown.
We've temporarily fixed the errors created by these bare links with downstream patches. But longer term, we'd like to avoid manually or automatically fixing these bare links each time we generate new markdown SDK docs.
tl;dr: docs build is picky, this fixes a problem at the source
Would you kindly consider changing these links to markdown formatting? I'm open to other solutions, and I know markdown formatting isn't perfect either, since these comments are otherwise written in plaintext. I'd like to preserve both the link for edification and our time/brittleness downstream. So if some other solution occurs to you, let me know.
@nicksanford introduced this link, and I hear through the grapevine that @JohnN193 might have a stance on this. If one of you could sanity check and review, I would appreciate it.
Tagging @stuqdog for context (but don't blame ethan for any mistakes I've made)
Thanks!