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
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 An ESLint team member will look at this issue soon documentation Relates to ESLint's documentation labels Jan 13, 2022
@JoshuaKGoldberg JoshuaKGoldberg marked this pull request as ready for review January 23, 2022 22:16
@snitin315 snitin315 added accepted There is consensus among the team that this change meets the criteria for inclusion and removed triage An ESLint team member will look at this issue soon labels Jan 24, 2022
docs/rules/eqeqeq.md Outdated Show resolved Hide resolved
Copy link
Member

@aladdin-add aladdin-add left a comment

Choose a reason for hiding this comment

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

LGTM~

Copy link
Contributor

@snitin315 snitin315 left a comment

Choose a reason for hiding this comment

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

LGTM. Thank you for contributing ❤️

@snitin315 snitin315 merged commit ccbc35f into eslint:main Jan 26, 2022
@JoshuaKGoldberg JoshuaKGoldberg deleted the docs-h1-trim branch January 26, 2022 05:22
@eslint-github-bot eslint-github-bot bot locked and limited conversation to collaborators Jul 26, 2022
@eslint-github-bot eslint-github-bot bot added the archived due to age This issue has been archived; please open a new issue for any further discussion label Jul 26, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
accepted There is consensus among the team that this change meets the criteria for inclusion archived due to age This issue has been archived; please open a new issue for any further discussion documentation Relates to ESLint's documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Documentation formatting change: move descriptions out of h1s
3 participants