Generate docs and push to gh-pages automatically (#3443)

* Generate docs and push to gh-pages

* Move to workflows

* Fix workflow

* Add support for unreleased linter versions

* Keep preexisting files

Author: parlough

.github/workflows/gh-pages.yml

@@ -0,0 +1,35 @@
+name: Deploy to GitHub Pages
+
+# Declare default permissions as read only.
+permissions: read-all
+
+on:
+  push:
+    branches:
+      - master
+jobs:
+  build-and-deploy-docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    if: github.repository == 'dart-lang/linter'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@d171c3b028d844f2bf14e9fdec0c58114451e4bf
+      - name: Setup Dart
+        uses: dart-lang/setup-dart@6a218f2413a3e78e9087f638a238f6b40893203d
+        with:
+          sdk: stable
+      - name: Get dependencies
+        run: dart pub get
+      - name: Generate docs
+        run: dart run tool/doc.dart --create-dirs --no-markdown --out lints --token ${{ secrets.GITHUB_TOKEN }}
+      - name: Deploy docs
+        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: lints
+          destination_dir: lints
+          keep_files: true

tool/doc.dart

@@ -21,7 +21,13 @@ import 'since.dart';
 void main(List<String> args) async {
   var parser = ArgParser()
     ..addOption('out', abbr: 'o', help: 'Specifies output directory.')
-    ..addOption('token', abbr: 't', help: 'Specifies a github auth token.');
+    ..addOption('token', abbr: 't', help: 'Specifies a github auth token.')
+    ..addFlag('create-dirs',
+        abbr: 'd', help: 'Enables creation of necessary directories.')
+    ..addFlag('markdown',
+        abbr: 'm',
+        help: 'Enables generation of the markdown docs.',
+        defaultsTo: true);
 
   ArgResults options;
   try {
@@ -36,7 +42,14 @@ void main(List<String> args) async {
   var token = options['token'];
   var auth = token is String ? Authentication.withToken(token) : null;
 
-  await generateDocs(outDir, auth: auth);
+  var createDirectories = options['create-dirs'] == true;
+
+  var enableMarkdown = options['markdown'] == true;
+
+  await generateDocs(outDir,
+      auth: auth,
+      createDirectories: createDirectories,
+      enableMarkdown: enableMarkdown);
 }
 
 const ruleFootMatter = '''
@@ -155,20 +168,33 @@ Future<void> fetchSinceInfo(Authentication? auth) async {
   sinceInfo = await getSinceMap(auth);
 }
 
-Future<void> generateDocs(String? dir, {Authentication? auth}) async {
+Future<void> generateDocs(String? dir,
+    {Authentication? auth,
+    bool createDirectories = false,
+    bool enableMarkdown = true}) async {
   var outDir = dir;
   if (outDir != null) {
     var d = Directory(outDir);
+    if (createDirectories) {
+      d.createSync();
+    }
+
     if (!d.existsSync()) {
       print("Directory '${d.path}' does not exist");
       return;
     }
+
     if (!File('$outDir/options').existsSync()) {
       var lintsChildDir = Directory('$outDir/lints');
       if (lintsChildDir.existsSync()) {
         outDir = lintsChildDir.path;
       }
     }
+
+    if (createDirectories) {
+      Directory('$outDir/options').createSync();
+      Directory('$outDir/machine').createSync();
+    }
   }
 
   registerLintRules();
@@ -185,12 +211,17 @@ Future<void> generateDocs(String? dir, {Authentication? auth}) async {
   // Generate rule files.
   for (var l in rules) {
     RuleHtmlGenerator(l).generate(outDir);
-    RuleMarkdownGenerator(l).generate(filePath: outDir);
+    if (enableMarkdown) {
+      RuleMarkdownGenerator(l).generate(filePath: outDir);
+    }
   }
 
   // Generate index.
   HtmlIndexer(Registry.ruleRegistry).generate(outDir);
-  MarkdownIndexer(Registry.ruleRegistry).generate(filePath: outDir);
+
+  if (enableMarkdown) {
+    MarkdownIndexer(Registry.ruleRegistry).generate(filePath: outDir);
+  }
 
   // Generate options samples.
   OptionsSample(rules).generate(outDir);
@@ -562,13 +593,14 @@ class RuleHtmlGenerator {
   String get name => rule.name;
 
   String get since {
-    var info = sinceInfo[name]!;
     // See: https://github.com/dart-lang/linter/issues/2824
+    // var info = sinceInfo[name]!;
     // var version = info.sinceDartSdk != null
     //     ? '>= ${info.sinceDartSdk}'
     //     : '<strong>unreleased</strong>';
     //return 'Dart SDK: $version • <small>(Linter v${info.sinceLinter})</small>';
-    return 'Linter v${info.sinceLinter}';
+    var sinceLinter = sinceInfo[name]!.sinceLinter;
+    return sinceLinter != null ? 'Linter v$sinceLinter' : 'Unreleased';
   }
 
   void generate([String? filePath]) {
@@ -641,13 +673,14 @@ class RuleMarkdownGenerator {
   String get name => rule.name;
 
   String get since {
-    var info = sinceInfo[name]!;
     // See: https://github.com/dart-lang/linter/issues/2824
+    // var info = sinceInfo[name]!;
     // var version = info.sinceDartSdk != null
     //     ? '>= ${info.sinceDartSdk}'
-    //     : '**unreleased**';
-    // return 'Dart SDK: $version • (Linter v${info.sinceLinter})';
-    return 'Linter v${info.sinceLinter}';
+    //     : '<strong>unreleased</strong>';
+    //return 'Dart SDK: $version • <small>(Linter v${info.sinceLinter})</small>';
+    var sinceLinter = sinceInfo[name]!.sinceLinter;
+    return sinceLinter != null ? 'Linter v$sinceLinter' : 'Unreleased';
   }
 
   void generate({String? filePath}) {