Skip to content
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.

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

docs: trimmed rules h1s to just be rule names #15514

Merged
merged 3 commits into from Jan 26, 2022

Conversation

JoshuaKGoldberg
Copy link
Sponsor Contributor

@JoshuaKGoldberg JoshuaKGoldberg commented Jan 13, 2022

Prerequisites checklist

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Moves the description of each rule out of its h1 and into a one-line sentence after.

Fixes #15471.

Is there anything you'd like reviewers to focus on?

There were actually quite a few rules that had different text in their docs heading compared to their meta.docs.description. Separate from this PR I'd suggest adding testing to make sure they stay in sync. I think a good heuristic to fix them all up would be to take the longer between the docs intro paragraph from this PR and the description from the rule itself. Aha, they're in the makefile! Fixing up now before un-drafting.

I didn't add a check that the docs page description matches the rule meta docs, because they generally don't. But if you'd like me to make that change in this PR I'd be happy to.

Here's a quick script I used to get these changes mostly done...
// docs/rules/migrate.mjs

import { promises as fs } from "fs";

const mdFiles = (await fs.readdir(".")).filter((x) => x.endsWith(".md"));
const problems = [];

for (const fileName of mdFiles) {
    try {
        await convertFile(fileName);
    } catch (error) {
        problems.push({ error, fileName });
    }
}

if (problems.length) {
    console.error("Problems!");

    for (const { error, fileName } of problems) {
        console.error(`${fileName}: ${error}`);
    }

    process.exitCode = 1;
}

async function convertFile(fileName) {
    const contents = (await fs.readFile(fileName)).toString();
    const [firstLine, ...remainingLines] = contents.split(/\n/);

    const { description, ruleName } = parseMetaFromLine(firstLine);

    const updatedLines = [`# ${ruleName}`, "", description, ...remainingLines];

    await fs.writeFile(fileName, updatedLines.join("\n"));
}

function parseMetaFromLine(line) {
    // Most rules start with the format:
    // # ${Description} (${rule-name})
    const descriptionFirst = line.match(/\# (.+) \((.+)\)/);
    if (descriptionFirst) {
        return {
            description: touchUpDescription(descriptionFirst[1]),
            ruleName: descriptionFirst[2],
        };
    }

    // ...except for a few oddities such as generator-star.md:
    // # ${rule-name}: ${Description}
    const ruleNameFirst = line.match(/# (.+): (.*)/);
    if (ruleNameFirst) {
        return {
            description: touchUpDescription(ruleNameFirst[2]),
            ruleName: ruleNameFirst[1],
        };
    }

    throw new Error("Unknown first line format.");
}

function touchUpDescription(description) {
    description = description[0].toUpperCase() + description.slice(1);

    // In retrospect, I wish I'd done replaces on "allow", "require", etc.
    let [firstWord, ...rest] = description.split(" ");
    if (firstWord.endsWith("e") || firstWord.endsWith("w")) {
        firstWord += "s";
    }
    description = [firstWord, ...rest].join(" ");

    if (!description.endsWith(".")) {
        description += ".";
    }

    return description;
}

@eslint-github-bot eslint-github-bot bot added triage documentation labels Jan 13, 2022
@JoshuaKGoldberg JoshuaKGoldberg marked this pull request as ready for review Jan 23, 2022
@snitin315 snitin315 added accepted and removed triage labels Jan 24, 2022
docs/rules/eqeqeq.md Outdated Show resolved Hide resolved
Copy link
Member

@aladdin-add aladdin-add left a comment

LGTM~

@JoshuaKGoldberg JoshuaKGoldberg requested a review from snitin315 Jan 26, 2022
Copy link
Contributor

@snitin315 snitin315 left a comment

LGTM. Thank you for contributing ❤️

@snitin315 snitin315 merged commit ccbc35f into eslint:main Jan 26, 2022
14 checks passed
@JoshuaKGoldberg JoshuaKGoldberg deleted the docs-h1-trim branch Jan 26, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
accepted documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants