From 9a070d2939c3f4450e794f8a6f82a43234ea59da Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Thu, 20 Jul 2023 11:54:12 -0500 Subject: [PATCH] Leave backup text crumbs pointing to new docs (#4582) * Leave backup text crumbs pointing to new docs * Revert addition of unreachable_from_main --- tool/doc.dart | 303 ++++---------------------------------------------- 1 file changed, 21 insertions(+), 282 deletions(-) diff --git a/tool/doc.dart b/tool/doc.dart index fe998eff7..da5b62e07 100644 --- a/tool/doc.dart +++ b/tool/doc.dart @@ -7,13 +7,11 @@ import 'dart:io'; import 'package:analyzer/src/lint/config.dart'; import 'package:analyzer/src/lint/registry.dart'; -import 'package:analyzer/src/lint/state.dart'; import 'package:args/args.dart'; import 'package:http/http.dart' as http; import 'package:linter/src/analyzer.dart'; import 'package:linter/src/rules.dart'; import 'package:linter/src/utils.dart'; -import 'package:markdown/markdown.dart'; import 'package:yaml/yaml.dart'; import 'machine.dart'; @@ -41,36 +39,6 @@ void main(List args) async { await generateDocs(outDir, createDirectories: createDirectories); } -const ruleFootMatter = ''' -In addition, rules can be further distinguished by *maturity*. Unqualified -rules are considered stable, while others may be marked **experimental** -to indicate that they are under review. Lints that are marked as **deprecated** -should not be used and are subject to removal in future Linter releases. - -Rules can be selectively enabled in the analyzer using -[analysis options](https://pub.dev/packages/analyzer) -or through an -[analysis options file](https://dart.dev/guides/language/analysis-options#the-analysis-options-file). - -* **An auto-generated list enabling all options is provided [here](options/options.html).** - -As some lints may contradict each other, only a subset of these will be -enabled in practice, but this list should provide a convenient jumping-off point. - -Many lints are included in various predefined rulesets: - -* [core](https://github.com/dart-lang/lints) for official "core" Dart team lint rules. -* [recommended](https://github.com/dart-lang/lints) for additional lint rules "recommended" by the Dart team. -* [flutter](https://github.com/flutter/packages/blob/main/packages/flutter_lints/lib/flutter.yaml) for rules recommended for Flutter projects (`flutter create` enables these by default). - -Rules included in these rulesets are badged in the documentation below. - -These rules are under active development. Feedback is -[welcome](https://github.com/dart-lang/linter/issues)! -'''; - -const ruleLeadMatter = 'Rules are organized into familiar rule groups.'; - final coreRules = []; final flutterRules = []; final recommendedRules = []; @@ -173,56 +141,19 @@ Future generateDocs(String? dir, {bool createDirectories = false}) async { // Generate rule files. for (var rule in rules) { - var fixStatus = getFixStatus(rule, fixStatusMap); - RuleHtmlGenerator(rule, fixStatus).generate(outDir); + RuleHtmlGenerator(rule).generate(outDir); } // Generate index. - HtmlIndexer(rules, fixStatusMap).generate(outDir); + HtmlIndexer().generate(outDir); // Generate options samples. - OptionsSample(rules).generate(outDir); + OptionsSample().generate(outDir); // Generate a machine-readable summary of rules. MachineSummaryGenerator(Registry.ruleRegistry, fixStatusMap).generate(outDir); } -String getBadges(String rule, [String? fixStatus]) { - var sb = StringBuffer(); - if (coreRules.contains(rule)) { - sb.write( - '' - 'core'); - } - if (recommendedRules.contains(rule)) { - sb.write( - '' - 'recommended'); - } - if (flutterRules.contains(rule)) { - sb.write( - '' - 'flutter'); - } - if (fixStatus == 'hasFix') { - sb.write( - '' - 'has-fix'); - } - return sb.toString(); -} - -String getFixStatus(LintRule rule, Map fixStatusMap) { - var fallback = 'unregistered'; - for (var code in rule.lintCodes) { - var status = fixStatusMap[code.uniqueName.substring(9)]; - if (status == null) continue; - if (status == 'hasFix') return status; - fallback = status; - } - return fallback; -} - void printUsage(ArgParser parser, [String? error]) { var message = 'Generates lint docs.'; if (error != null) { @@ -252,27 +183,7 @@ class CountBadger { } class HtmlIndexer { - final Iterable rules; - final Map fixStatusMap; - HtmlIndexer(this.rules, this.fixStatusMap); - - String get enumerateErrorRules => rules - .where((r) => r.group == Group.errors) - .map(toDescription) - .join('\n\n'); - - String get enumerateGroups => Group.builtin - .map((Group g) => - '
  • ${g.name} - ${markdownToHtml(g.description)}
    • ') - .join('\n'); - - String get enumeratePubRules => - rules.where((r) => r.group == Group.pub).map(toDescription).join('\n\n'); - - String get enumerateStyleRules => rules - .where((r) => r.group == Group.style) - .map(toDescription) - .join('\n\n'); + HtmlIndexer(); void generate(String? filePath) { var generated = _generate(); @@ -285,9 +196,6 @@ class HtmlIndexer { } } - String toDescription(LintRule r) => - '${r.qualifiedName}
    ${getBadges(r.name, fixStatusMap[r.name])} ${markdownToHtml(r.description)}'; - String _generate() => ''' @@ -305,45 +213,16 @@ class HtmlIndexer {
    - -

    Linter for Dart

    -     -

    Lint Rules

    - -

    Using the Linter

    +

    Linter for Dart
    - -

    Supported Lint Rules

    +

    Linter documentation has moved!

    - This list is auto-generated from our sources. + Find up-to-date linter and lint rule documentation at + https://dart.dev/lints.

    - ${markdownToHtml(ruleLeadMatter)} -
      - $enumerateGroups -
    - ${markdownToHtml(ruleFootMatter)} - -

    Error Rules

    - - $enumerateErrorRules - -

    Style Rules

    - - $enumerateStyleRules - -

    Pub Rules

    - - $enumeratePubRules -
    - '''; @@ -369,9 +248,7 @@ class MachineSummaryGenerator { } class OptionsSample { - Iterable rules; - - OptionsSample(this.rules); + OptionsSample(); void generate(String? filePath) { var generated = _generate(); @@ -384,26 +261,6 @@ class OptionsSample { } } - String generateOptions() { - var sb = StringBuffer(''' -``` -linter: - rules: -'''); - - var sortedRules = rules - .where((r) => !r.state.isDeprecated && !r.state.isRemoved) - .map((r) => r.name) - .toList() - ..sort(); - for (var rule in sortedRules) { - sb.write(' - $rule\n'); - } - sb.write('```'); - - return sb.toString(); - } - String _generate() => ''' @@ -421,35 +278,16 @@ linter:
    - -

    Linter for Dart

    -     -

    Analysis Options

    - -

    View all Lint Rules

    -

    Using the Linter

    +

    All linter rules enabled
    - -

    Analysis Options

    +

    Linter documentation has moved!

    - Auto-generated options enabling all lints. - Add these to your - analysis_options.yaml file - and tailor to fit! + Find an auto-generated list of all linter rules at + https://dart.dev/lints/all.

    - - ${markdownToHtml(generateOptions())} -
    - '''; @@ -457,84 +295,11 @@ linter: class RuleHtmlGenerator { final LintRule rule; - final String fixStatus; - - RuleHtmlGenerator(this.rule, this.fixStatus); - - String get details => rule.details; - String get group => rule.group.name; - - String get humanReadableName => rule.name; + RuleHtmlGenerator(this.rule); String get name => rule.name; - State get state => rule.state; - - String get usageMarkdown => ''' -## Usage - -To enable the `$name` lint, -add `$name` under **linter > rules** in your -[`analysis_options.yaml`](https://dart.dev/guides/language/analysis-options) -file: - -```yaml -linter: - rules: - - $name -``` - '''; - - String get detailsHeader { - if (state.isRemoved) { - var version = state.since; - var sinceDetail = - version != null ? ' since Dart language version $version.' : ''; - return '

    Unsupported$sinceDetail

    '; - } - return ''; - } - - String get incompatibleRuleDetails { - var sb = StringBuffer(); - var incompatibleRules = rule.incompatibleRules; - if (incompatibleRules.isNotEmpty) { - sb.writeln('

    '); - sb.write('Incompatible with: '); - var rule = incompatibleRules.first; - sb.write( - '$rule'); - for (var i = 1; i < incompatibleRules.length; ++i) { - rule = incompatibleRules[i]; - sb.write(', $rule'); - } - sb.writeln('.'); - sb.writeln('

    '); - } - return sb.toString(); - } - - String get since { - var info = sinceMap[name]!; - var sdkVersion = info.sinceDartSdk != null - ? '>= ${info.sinceDartSdk}' - : 'Unreleased'; - return 'Dart SDK: $sdkVersion'; - } - - String get stateString { - if (state.isDeprecated) { - return '${state.label}'; - } else if (state.isRemoved) { - return '${state.label}'; - } else if (state.isExperimental) { - return '${state.label}'; - } else { - return state.label; - } - } - void generate([String? filePath]) { var generated = _generate(); if (filePath != null) { @@ -563,44 +328,18 @@ linter:
    -

    $humanReadableName

    -

    Group: $group

    -

    Maturity: $stateString

    -
    -

    $since

    - Since info is static, may be stale -
    - ${getBadges(name, fixStatus)} - -

    View all Lint Rules

    -

    Using the Linter

    +

    $name
    - $detailsHeader - ${markdownToHtml(details)} - $incompatibleRuleDetails - ${markdownToHtml(usageMarkdown)} +

    Lint documentation has moved!

    +

    + Find up-to-date documentation for the + $name linter rule at + https://dart.dev/lints/$name. +

    - '''; } - -extension on State { - String get describe => isStable ? '' : ' ($label)'; -} - -extension on LintRule { - String get qualifiedName { - var label = state.isRemoved ? '$name' : name; - return label + state.describe; - } -}