-
-
Notifications
You must be signed in to change notification settings - Fork 107
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
Rule documentation in metadata #48
Comments
This sounds like a good idea and something I wasn't aware of. We can likely just have docs in the github repo and then point to them correct? |
Yep! A common tactic is to generate the URL to point to the specific release tag of the version the user is running, so if the documentation has changed at a later point as the rule updates they aren't seeing conflicting information. If I were to implement it currently I would use something like this: import { basename } from 'path';
const pkg = require('../../package');
const repoUrl = 'https://github.com/nodesecurity/eslint-plugin-security';
/**
* Return the URL of the rule's documentation, either from parameter or the
* requiring file's name.
* @param {String} ruleName The name of the rule to generate a URL for.
* Defaults to the name of the calling file.
* @param {String} commitHash Hash of a specific ommit or tag name, defaults
* to the current package version.
* @return {String} The URL of the rule's documentation.
*/
const getDocsUrl = (ruleName, commitHash) => {
ruleName = ruleName || path.basename(module.parent.filename, '.js');
commitHash = commitHash || `v${pkg.version}`;
return `${repoUrl}/blob/${commitHash}/docs/rules/${ruleName}.md`;
}; That's a combination of functionality from a few different previous PR's where I implemented this, you can check these for further examples on how to use the above function 😉: |
Summary Still relevant? Next steps
|
I propose a simplified PR compared to #61 which adds only meta descriptions, and doesn't modify code with unused variables etc. It should be conflictless. I will look into a PR draft. |
ESLint defines a metadata property (
meta.docs.url
) for rules to specify a URL where the full documentation for the rule can be found.One of your users recently submitted jfmengels/eslint-rule-documentation#35 to get documentation links showing in some places, but this should be being specified using the metadata property so anywhere that supports ESLint rules will know the proper link to the documentation.
Ideally while solving this you probably should move the documentation into a
docs/rule-name.md
structure to allow for greater detail for each rule (and cleaner links), but that isn't a requirement 😉.Note: This was originally filed as #1, but I believe that may have been before ESLint added the metadata property.
The text was updated successfully, but these errors were encountered: