Skip to content

don't emit rustdoc::broken_intra_doc_links for stuff like [!NOTE] #144921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

don't emit rustdoc::broken_intra_doc_links for stuff like [!NOTE] #144921

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions src/librustdoc/passes/collect_intra_doc_links.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -997,6 +997,7 @@ fn preprocess_link(
}
};

let is_shortcut_style = ori_link.kind == LinkType::ShortcutUnknown;
// If there's no backticks, be lenient and revert to the old behavior.
// This is to prevent churn by linting on stuff that isn't meant to be a link.
// only shortcut links have simple enough syntax that they
Expand All @@ -1013,11 +1014,25 @@ fn preprocess_link(
// | has backtick | never ignore | never ignore |
// | no backtick | ignore if url-like | never ignore |
// |-------------------------------------------------------|
let ignore_urllike =
can_be_url || (ori_link.kind == LinkType::ShortcutUnknown && !ori_link.link.contains('`'));
let ignore_urllike = can_be_url || (is_shortcut_style && !ori_link.link.contains('`'));
if ignore_urllike && should_ignore_link(path_str) {
return None;
}
// ignore github flavored markdown special blockquotes,
// such as [!NOTE] and [!IMPORTANT]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you elaborate the comment slightly noting that it's ~common for people to include_str the README.md of their GitHub repo?

I think we want to highlight that cuz rustdoc doesn't use GitHub-flavored Markdown and doesn't support GitHub-style admonitions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, good point, will elaborate.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

alright, I expanded the documentation and also made sure that [!] is still parsed as a link to the never type.

//
// rustdoc does not support github-flavored markdown,
// however it is a common pattern to add #[doc = include_str!("../README.md")] to the root of a crate,
// so we want to at least accept github-flavored markdown, even if it doesn't render perfectly.
//
// we do allow [!] as a link to the never type.
if is_shortcut_style
&& ori_link.link.starts_with('!')
&& ori_link.link.len() > 1
&& ori_link.link[1..].chars().all(|c| c.is_ascii_alphabetic())
{
return None;
}

// Strip generics from the path.
let path_str = match strip_generics_from_path(path_str) {
Expand Down
6 changes: 6 additions & 0 deletions tests/rustdoc-ui/intra-doc/github-flavored-blockquote.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
// regression test for https://github.com/rust-lang/rust/issues/141866
//@ check-pass
#![deny(rustdoc::broken_intra_doc_links)]

//! > [!NOTE]
//! > This should not cause any warnings
Loading