doc(website): Show lint groups in TOC
MODIFY
website/src/credits.md
website/src/credits.md
@@ -109,7 +109,7 @@ layout: layouts/page.liquid
{% include ./contributors.md %}
-### Acknowledgements
+## Acknowledgements
Rome contains code that is heavily inspired from other projects. They have been adapted to Rome's
language/infrastructure.

MODIFY
xtask/lintdoc/src/main.rs
xtask/lintdoc/src/main.rs
@@ -87,62 +87,78 @@ fn main() -> Result<()> {
let mut visitor = LintRulesVisitor::default();
visit_registry(&mut visitor);
- let LintRulesVisitor { groups } = visitor;
+ let LintRulesVisitor { mut groups } = visitor;
+
+ let nursery_rules = groups
+ .remove("nursery")
+ .expect("Expected nursery group to exist");
for (group, rules) in groups {
+ generate_group(group, rules, &root, &mut index, &mut errors)?;
+ }
+
+ generate_group("nursery", nursery_rules, &root, &mut index, &mut errors)?;
+
+ if !errors.is_empty() {
+ bail!(
+ "failed to generate documentation pages for the following rules:\n{}",
+ errors
+ .into_iter()
+ .map(|(rule, err)| format!("- {rule}: {err:?}\n"))
+ .collect::<String>()
+ );
+ }
+
+ fs2::write(root.join("index.md"), index)?;
+
+ Ok(())
+}
+
+fn generate_group(
+ group: &'static str,
+ rules: BTreeMap<&'static str, RuleMetadata>,
+ root: &Path,
+ mut index: &mut dyn io::Write,
+ errors: &mut Vec<(&'static str, Error)>,
+) -> io::Result<()> {
let (group_name, description) = match group {
"correctness" => (
"Correctness",
markup! {
- "This group should includes those rules that are meant to prevent possible bugs and misuse of the language."
+ "Rules that detect incorrect or useless code."
},
),
"nursery" => (
"Nursery",
markup! {
- "Rules that are being written. Rules under this group are meant to be considered unstable or buggy.
-
-Developers can opt-in these rules via configuration. We vehemently appreciate filing issue in case of bugs or performance problems.
-
-Rules can be downgraded to this group in case a patch release is needed. After an arbitrary amount of time, the team can decide
-to promote these rules into an appropriate group. Doing so means that the rule is stable and ready for production."
+ "New rules that are still under development.
+Nursery rules require explicit opt-in via configuration because they may still have bugs or performance problems.
+Nursery rules get promoted to other groups once they become stable or may be removed."
},
),
"style" => (
"Style",
markup! {
- "Rules that focus mostly on making the code more consistent."
+ "Rules enforcing a consistent way of writing your code. "
},
),
_ => panic!("Unknown group ID {group:?}"),
};
- writeln!(index, "<section>")?;
- writeln!(index, "<h2>{group_name}<a class=\"header-anchor\" href=\"#{group_name}\" aria-label=\"{group_name}\"></a></h2>")?;
+ writeln!(index, "\n## {group_name}")?;
writeln!(index)?;
- markup_to_string(&mut index, description)?;
+ markup_to_string(index, description)?;
writeln!(index)?;
for (rule, meta) in rules {
- let version = meta.version;
- match generate_rule(
- &root,
- group,
- rule,
- meta.docs,
- meta.version,
- meta.recommended,
- ) {
+ match generate_rule(root, group, rule, meta.docs, meta.version, meta.recommended) {
Ok(summary) => {
- writeln!(index, "<div class=\"rule\">")?;
+ writeln!(index, "<section class=\"rule\">")?;
writeln!(index, "<h3 data-toc-exclude id=\"{rule}\">")?;
- writeln!(
- index,
- " <a href=\"/docs/lint/rules/{rule}\">{rule} (since v{version})</a>"
- )?;
- writeln!(index, " <a class=\"header-anchor\" href=\"#{rule}\"></a>")?;
+ writeln!(index, " <a href=\"/docs/lint/rules/{rule}\">{rule}</a>")?;
+
if meta.recommended {
writeln!(index, " <span class=\"recommended\">recommended</span>")?;
}
@@ -150,7 +166,7 @@ to promote these rules into an appropriate group. Doing so means that the rule i
write_html(&mut index, summary.into_iter())?;
- writeln!(index, "\n</div>")?;
+ writeln!(index, "\n</section>")?;
}
Err(err) => {
errors.push((rule, err));
@@ -158,21 +174,6 @@ to promote these rules into an appropriate group. Doing so means that the rule i
}
}
- writeln!(index, "</section>")?;
- }
-
- if !errors.is_empty() {
- bail!(
- "failed to generate documentation pages for the following rules:\n{}",
- errors
- .into_iter()
- .map(|(rule, err)| format!("- {rule}: {err:?}\n"))
- .collect::<String>()
- );
- }
-
- fs2::write(root.join("index.md"), index)?;
-
Ok(())
}
@@ -555,7 +556,7 @@ fn assert_lint(
Ok(())
}
-pub fn markup_to_string(buffer: &mut Vec<u8>, markup: Markup) -> io::Result<()> {
+pub fn markup_to_string(buffer: &mut dyn io::Write, markup: Markup) -> io::Result<()> {
let mut write = HTML(buffer);
let mut fmt = Formatter::new(&mut write);
fmt.write_markup(markup)

doc(website): Show lint groups in TOC (#3470)