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

chore: Refactor rule docs format #15869

Merged
merged 2 commits into from May 13, 2022
Merged

chore: Refactor rule docs format #15869

merged 2 commits into from May 13, 2022

Conversation

nzakas
Copy link
Member

@nzakas nzakas commented May 11, 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)

To get the new docs site up and running, I've made a couple changes to the way rule pages are rendered:

  1. Related rules are now represented in the related_rules frontmatter key instead of plain markdown
  2. Further reading links are now represented in the further_reading frontmatter key instead of plain markdown

This allows us to automatically format this data in a pretty way on the website and ensures consistent ordering.

I updated two rules as examples: no-ternary and block-scoped-var.

Related change in current website: eslint/archive-website#943

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

With the new docs site, the title of the further reading URLs is fetched automatically. In the current website, we were hard-coding those, so with this approach we will lose the article title on the current website. I think this is a worthwhile tradeoff in the short-term.

Any concerns about this approach?

@eslint-github-bot eslint-github-bot bot added triage An ESLint team member will look at this issue soon chore This change is not user-facing labels May 11, 2022
@netlify
Copy link

netlify bot commented May 11, 2022

Deploy Preview for docs-eslint ready!

Name Link
🔨 Latest commit 9526538
🔍 Latest deploy log https://app.netlify.com/sites/docs-eslint/deploys/627c2191c6fc94000940a07f
😎 Deploy Preview https://deploy-preview-15869--docs-eslint.netlify.app/rules/block-scoped-var
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@mdjermanovic
Copy link
Member

With the new docs site, the title of the further reading URLs is fetched automatically.

Should we account for the possibility that external URLs can become broken (temporarily or permanently)? For example, I added -foo to the adequatelygood URL in block-scoped-var to make it 404, and the whole build (npm start) breaks, so it seems that our site deploy will fail whenever there's a broken external link. which seems fragile.

[11ty] Problem writing Eleventy templates: (more in DEBUG output)
[11ty] 1. Having trouble writing template: "_site/rules/block-scoped-var/index.html" (via EleventyTemplateError)
[11ty] 2. (./src/_includes/layouts/doc.html)
[11ty]   EleventyShortcodeError: Error with Nunjucks shortcode `link` (via Template render error)
[11ty] 3. Response code 404 (Not Found) (via Template render error)
[11ty]
[11ty] Original error stack trace: HTTPError: Response code 404 (Not Found)

@nzakas
Copy link
Member Author

nzakas commented May 12, 2022

Yes, I'll work on that at a later step. Right now, just trying to get something working and deployed.

@mdjermanovic
Copy link
Member

In the current website, we were hard-coding those, so with this approach we will lose the article title on the current website. I think this is a worthwhile tradeoff in the short-term.

Sounds good to me.

Any concerns about this approach?

Only #15869 (comment).

Copy link
Member

@mdjermanovic mdjermanovic left a comment

Choose a reason for hiding this comment

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

This LGTM!

Did you plan to update the remaining rules in this PR or in another PR? (I could take that task)

@nzakas
Copy link
Member Author

nzakas commented May 13, 2022

I was going to open a separate issue for completing the remaining rules and asking everyone to pitch in to help.

@nzakas nzakas merged commit 5891c75 into main May 13, 2022
@nzakas nzakas deleted the docs-rules branch May 13, 2022 23:27
crapStone pushed a commit to Calciumdibromid/CaBr2 that referenced this pull request May 24, 2022
This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
| [eslint](https://eslint.org) ([source](https://github.com/eslint/eslint)) | devDependencies | minor | [`8.15.0` -> `8.16.0`](https://renovatebot.com/diffs/npm/eslint/8.15.0/8.16.0) |

---

### Release Notes

<details>
<summary>eslint/eslint</summary>

### [`v8.16.0`](https://github.com/eslint/eslint/releases/tag/v8.16.0)

[Compare Source](eslint/eslint@v8.15.0...v8.16.0)

#### Features

-   [`cab0c22`](eslint/eslint@cab0c22) feat: add Unicode flag suggestion in no-misleading-character-class ([#&#8203;15867](eslint/eslint#15867)) (Milos Djermanovic)
-   [`38ae956`](eslint/eslint@38ae956) feat: check Unicode code point escapes in no-control-regex ([#&#8203;15862](eslint/eslint#15862)) (Milos Djermanovic)
-   [`ee69cd3`](eslint/eslint@ee69cd3) feat: Update global variables ([#&#8203;15871](eslint/eslint#15871)) (Sébastien Règne)

#### Bug Fixes

-   [`3f09aab`](eslint/eslint@3f09aab) fix: function-paren-newline crash on "new new Foo();" ([#&#8203;15850](eslint/eslint#15850)) (coderaiser)

#### Documentation

-   [`050d5f4`](eslint/eslint@050d5f4) docs: Static further reading links ([#&#8203;15890](eslint/eslint#15890)) (Nicholas C. Zakas)
-   [`36287c0`](eslint/eslint@36287c0) docs: fix absolute paths in related rules shortcode to work from /docs ([#&#8203;15892](eslint/eslint#15892)) (Milos Djermanovic)
-   [`90b6990`](eslint/eslint@90b6990) docs: fix absolute links in rule macro to work from /docs ([#&#8203;15891](eslint/eslint#15891)) (Milos Djermanovic)
-   [`f437249`](eslint/eslint@f437249) docs: Adjust docs site path prefix ([#&#8203;15889](eslint/eslint#15889)) (Nicholas C. Zakas)
-   [`6e16025`](eslint/eslint@6e16025) docs: update 'Related Rules' and 'Further Reading' in remaining rules ([#&#8203;15884](eslint/eslint#15884)) (Milos Djermanovic)
-   [`1d39f69`](eslint/eslint@1d39f69) docs: remove confusing examples for no-mixed-operators ([#&#8203;15875](eslint/eslint#15875)) (Milos Djermanovic)
-   [`3071d76`](eslint/eslint@3071d76) docs: Fix some grammar issues ([#&#8203;15837](eslint/eslint#15837)) (byodian)

#### Chores

-   [`1768d0d`](eslint/eslint@1768d0d) chore: upgrade [@&#8203;eslint/eslintrc](https://github.com/eslint/eslintrc)[@&#8203;1](https://github.com/1).3.0 ([#&#8203;15903](eslint/eslint#15903)) (Milos Djermanovic)
-   [`c686e4c`](eslint/eslint@c686e4c) chore: Add deploy workflow for docs site ([#&#8203;15894](eslint/eslint#15894)) (Nicholas C. Zakas)
-   [`c7894cd`](eslint/eslint@c7894cd) chore: enable some rules from eslint-plugin-unicorn internally ([#&#8203;15878](eslint/eslint#15878)) (Bryan Mishkin)
-   [`ea65cb5`](eslint/eslint@ea65cb5) chore: upgrade eslint-plugin-eslint-plugin@^4.2.0 ([#&#8203;15882](eslint/eslint#15882)) (唯然)
-   [`cc29c69`](eslint/eslint@cc29c69) chore: Upgrade official GitHub actions to latest versions ([#&#8203;15880](eslint/eslint#15880)) (Darius Dzien)
-   [`5891c75`](eslint/eslint@5891c75) chore: Refactor rule docs format ([#&#8203;15869](eslint/eslint#15869)) (Nicholas C. Zakas)

</details>

---

### Configuration

📅 **Schedule**: At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, click this checkbox.

---

This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

Co-authored-by: cabr2-bot <cabr2.help@gmail.com>
Reviewed-on: https://codeberg.org/Calciumdibromid/CaBr2/pulls/1366
Reviewed-by: 6543 <6543@noreply.codeberg.org>
Co-authored-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>
Co-committed-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>
srijan-deepsource pushed a commit to DeepSourceCorp/eslint that referenced this pull request May 30, 2022
* chore: Refactor rule docs format

* Fix HTTP -> HTTPS
srijan-deepsource added a commit to DeepSourceCorp/eslint that referenced this pull request May 30, 2022
@eslint-github-bot eslint-github-bot bot locked and limited conversation to collaborators Nov 10, 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 Nov 10, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
archived due to age This issue has been archived; please open a new issue for any further discussion chore This change is not user-facing triage An ESLint team member will look at this issue soon
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants