Add a link to the nursery; tweak icons (#5637)

## Summary

We now always render the icons, but very faintly if inactive, and always
right-align. This ensures consistent alignment as you scroll down the
page:

<img width="1792" alt="Screen Shot 2023-07-09 at 10 45 50 PM"
src="https://github.com/astral-sh/ruff/assets/1309177/da47ac0e-d646-49e1-bbe1-9f43adf94bb4">

crates/ruff/src/rules/perflint/rules/try_except_in_loop.rs

@@ -45,7 +45,7 @@ use crate::settings::types::PythonVersion;
 /// try:
 ///     for num in string_numbers:
 ///         int_numbers.append(int(num))
-/// except ValueError as e
+/// except ValueError as e:
 ///     print(f"Couldn't convert to integer: {e}")
 /// ```
 ///

crates/ruff_dev/src/generate_rules_table.rs

@@ -11,19 +11,21 @@ const FIX_SYMBOL: &str = "🛠";
 const NURSERY_SYMBOL: &str = "🌅";
 
 fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>, linter: &Linter) {
-    table_out.push_str("| Code | Name | Message | Status |");
+    table_out.push_str("| Code | Name | Message | |");
     table_out.push('\n');
-    table_out.push_str("| ---- | ---- | ------- | ------ |");
+    table_out.push_str("| ---- | ---- | ------- | ------: |");
     table_out.push('\n');
     for rule in rules {
         let fix_token = match rule.autofixable() {
-            AutofixKind::None => "",
-            AutofixKind::Always | AutofixKind::Sometimes => FIX_SYMBOL,
+            AutofixKind::Always | AutofixKind::Sometimes => {
+                format!("<span style='opacity: 1'>{FIX_SYMBOL}</span>")
+            }
+            AutofixKind::None => format!("<span style='opacity: 0.1'>{FIX_SYMBOL}</span>"),
         };
         let nursery_token = if rule.is_nursery() {
-            NURSERY_SYMBOL
+            format!("<span style='opacity: 1'>{NURSERY_SYMBOL}</span>")
         } else {
-            ""
+            format!("<span style='opacity: 0.1'>{NURSERY_SYMBOL}</span>")
         };
         let status_token = format!("{fix_token} {nursery_token}");
 
@@ -48,10 +50,19 @@ fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>,
 
 pub(crate) fn generate() -> String {
     // Generate the table string.
-    let mut table_out = format!(
-        "The {FIX_SYMBOL} emoji indicates that a rule is automatically fixable by the `--fix` command-line option.\n\
-        The {NURSERY_SYMBOL} emoji indicates that a rule is part of the nursery, a collection of newer lints that are still under development.\n\n"
-    );
+    let mut table_out = String::new();
+
+    table_out.push_str(&format!(
+        "The {FIX_SYMBOL} emoji indicates that a rule is automatically fixable by the `--fix` command-line option."));
+    table_out.push('\n');
+    table_out.push('\n');
+
+    table_out.push_str(&format!(
+        "The {NURSERY_SYMBOL} emoji indicates that a rule is part of the [\"nursery\"](../faq/#what-is-the-nursery)."
+    ));
+    table_out.push('\n');
+    table_out.push('\n');
+
     for linter in Linter::iter() {
         let codes_csv: String = match linter.common_prefix() {
             "" => linter

docs/faq.md

@@ -370,6 +370,38 @@ matter how they're provided, which avoids accidental incompatibilities and simpl
 By default, no `convention` is set, and so the enabled rules are determined by the `select` setting
 alone.
 
+## What is the "nursery"?
+
+The "nursery" is a collection of newer rules that are considered experimental or unstable.
+
+If a rule is marked as part of the "nursery", it can only be enabled via direct selection. For
+example, consider a hypothetical rule, `HYP001`. If `HYP001` were included in the "nursery", it
+could be enabled by adding the following to your `pyproject.toml`:
+
+```toml
+[tool.ruff]
+extend-select = ["HYP001"]
+```
+
+However, it would _not_ be enabled by selecting the `HYP` category, like so:
+
+```toml
+[tool.ruff]
+extend-select = ["HYP"]
+```
+
+Similarly, it would _not_ be enabled via the `ALL` selector:
+
+```toml
+[tool.ruff]
+select = ["ALL"]
+```
+
+(The "nursery" terminology comes from [Clippy](https://doc.rust-lang.org/nightly/clippy/), a similar
+tool for linting Rust code.)
+
+To see which rules are currently in the "nursery", visit the [rules reference](https://beta.ruff.rs/docs/rules/).
+
 ## How can I tell what settings Ruff is using to check my code?
 
 Run `ruff check /path/to/code.py --show-settings` to view the resolved settings for a given file.