Merge branch 'main' into misc/sass-nesting-final

Author: parlough

.github/workflows/scorecards-analysis.yml

@@ -41,14 +41,14 @@ jobs:
 
       # Upload the results as artifacts (optional).
       - name: "Upload artifact"
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
         with:
           name: SARIF file
           path: results.sarif
           retention-days: 5
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@b56ba49b26e50535fa1e7f7db0f4f7b4bf65d80d
+        uses: github/codeql-action/upload-sarif@1b549b9259bda1cb5ddde3b41741a82a2d15a841
         with:
           sarif_file: results.sarif

.github/workflows/test.yaml

@@ -46,7 +46,7 @@ jobs:
         run: echo "name=today::$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
         shell: bash
       - name: Cache clean flutter
-        uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
         if: matrix.job == 'flutter'
         env:
           # Increment version to invalidate bad/obsolete caches.
@@ -55,7 +55,7 @@ jobs:
           path: ~/.dartdoc_grinder
           key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ steps.date.outputs.today }}
       - name: Cache .pub-cache
-        uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
         if: matrix.job == 'flutter'
         env:
           # Increment version to invalidate bad/obsolete caches.

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 8.3.4-wip
+* The URL for category pages now uses _category name_ instead of
+  _category `displayName`_.
+
 ## 8.3.3
 
 * Require Dart 3.6 or later.

README.md

@@ -109,21 +109,21 @@ its children that have the `@nodoc` tag in the documentation comment.
 
 ### dartdoc_options.yaml
 
-Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc
+Creating a file named `dartdoc_options.yaml` at the top of your package can change how Dartdoc
 generates docs.
 
 An example (not necessarily recommended settings):
 
 ```yaml
 dartdoc:
   categories:
-    "First Category":
+    awesome:
       markdown: doc/First.md
-      name: Awesome
-    "Second Category":
+      displayName: Awesome
+    great:
       markdown: doc/Second.md
-      name: Great
-  categoryOrder: ["First Category", "Second Category"]
+      displayName: Great
+  categoryOrder: [awesome, great]
   includeExternal: ['bin/unusually_located_library.dart']
   nodoc: ['lib/sekret/*.dart']
   linkTo:
@@ -137,17 +137,20 @@ dartdoc:
     - tool-error
 ```
 
-#### dartdoc_options.yaml fields
+#### `dartdoc_options.yaml` fields
 
 In general, **paths are relative** to the directory of the `dartdoc_options.yaml` file in which the option
 is defined, and should be specified as POSIX paths.  Dartdoc will convert POSIX paths automatically on Windows.
 Unrecognized options will be ignored.  Supported options:
 
-  * **categories**:  More details for each category/topic.  For topics you'd like to document, specify
-    the markdown file with `markdown:` to use for the category page.  Optionally, rename the
-    category from the source code into a display name with `name:`.  If there is no matching category
-    defined in dartdoc_options.yaml, those declared categories in the source code will be invisible.
-  * **categoryOrder**:  Specify the order of topics for display in the sidebar and
+  * **categories**: A map from _category names_ to _category definitions_.
+    The _category definition_ consists of a `markdown:` property and an optional `displayName:` property.
+    For topics you'd like to document, specify a _markdown file_ to be rendered on the category page,
+    using the `markdown:` property.
+    Optionally, you may specify a `displayName:` to be used in the rendered HTML, instead of the _category name_.
+    Categories are referenced in documentation comments using the `{@category <category name>}` tag.
+    Categories with no matching _category name_ defined in `dartdoc_options.yaml` will be invisible.
+  * **categoryOrder**:  A list of _category names_ specifying the order of topics for display in the sidebar and
     the package page.
   * **exclude**:  Specify a list of library names to avoid generating docs for,
     overriding any specified in include.  All libraries listed must be local to this package, unlike
@@ -210,12 +213,12 @@ You can tag libraries or top level classes, functions, and variables in their do
 the string `{@category YourCategory}`.  For libraries, that will cause the library to appear in a
 category when showing the sidebar on the Package and Library pages.  For other types of objects,
 the `{@category}` will be shown with a link to the category page **but only if specified in
-dartdoc_options.yaml**, as above.
+`dartdoc_options.yaml`**, as above.
 
 ```dart
 /// Here is my library.
 ///
-/// {@category Amazing}
+/// {@category awesome}
 library my_library;
 ```
 

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.3.3/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.3.4-wip/%f%#L%l%'

lib/src/model/category.dart

@@ -2,7 +2,6 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-
 import 'package:analyzer/dart/element/element2.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
@@ -78,7 +77,6 @@ class Category
     }
   }
 
-
   @override
   Element2? get element => null;
 
@@ -107,7 +105,10 @@ class Category
   late final bool isDocumented =
       documentedWhere != DocumentLocation.missing && documentationFile != null;
 
-  String get filePath => 'topics/$name-topic.html';
+  String get filePath {
+    assert(_name != null);
+    return 'topics/$_name-topic.html';
+  }
 
   @override
   String? get href => isCanonical ? '${package.baseHref}$filePath' : null;

lib/src/model/package_builder.dart

@@ -5,7 +5,6 @@
 import 'dart:async';
 
 import 'package:analyzer/dart/analysis/analysis_context.dart';
-import 'package:analyzer/dart/analysis/context_root.dart';
 import 'package:analyzer/dart/analysis/results.dart';
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/element/element2.dart';
@@ -64,9 +63,8 @@ class PubPackageBuilder implements PackageBuilder {
       // of handling it ourselves?
       resourceProvider: packageMetaProvider.resourceProvider,
       sdkPath: config.sdkDir,
-      updateAnalysisOptions2: ({
+      updateAnalysisOptions3: ({
         required AnalysisOptionsImpl analysisOptions,
-        required ContextRoot contextRoot,
         required DartSdk sdk,
       }) =>
           analysisOptions

pubspec.yaml

@@ -1,5 +1,5 @@
 name: dartdoc
-version: 8.3.3
+version: 8.3.4-wip
 description: A non-interactive HTML documentation generator for Dart source code.
 repository: https://github.com/dart-lang/dartdoc
 

test/end2end/model_test.dart

@@ -720,13 +720,13 @@ void main() async {
       expect(
           category.categoryLabel,
           '<span class="category superb cp-0 linked" title="This is part of the Superb topic.">'
-          '<a href="${htmlBasePlaceholder}topics/Superb-topic.html">Superb</a></span>');
+          '<a href="${htmlBasePlaceholder}topics/Excellent-topic.html">Superb</a></span>');
     });
 
     test('CategoryRendererHtml renders linkedName', () {
       var category = packageGraph.publicPackages.first.categories.first;
       expect(category.linkedName,
-          '<a href="${htmlBasePlaceholder}topics/Superb-topic.html">Superb</a>');
+          '<a href="${htmlBasePlaceholder}topics/Excellent-topic.html">Superb</a>');
     });
   });
 

tool/task.dart

@@ -9,7 +9,6 @@ import 'package:analyzer/file_system/physical_file_system.dart';
 import 'package:args/args.dart';
 import 'package:collection/collection.dart';
 import 'package:crypto/crypto.dart' as crypto;
-import 'package:dartdoc/src/io_utils.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:path/path.dart' as path;
 import 'package:sass/sass.dart' as sass;
@@ -497,12 +496,7 @@ Future<void> docSdk({bool withStats = false}) async => _docSdk(
 Map<String, String> createThrowawayPubCache() {
   var pubCache = Directory.systemTemp.createTempSync('pubcache');
   var pubCacheBin = Directory(path.join(pubCache.path, 'bin'));
-  var defaultCache = Directory(_defaultPubCache);
-  if (defaultCache.existsSync()) {
-    io_utils.copy(defaultCache, pubCache);
-  } else {
-    pubCacheBin.createSync();
-  }
+  pubCacheBin.createSync();
   return Map.fromIterables([
     'PUB_CACHE',
     'PATH',
@@ -512,9 +506,6 @@ Map<String, String> createThrowawayPubCache() {
   ]);
 }
 
-final String _defaultPubCache = Platform.environment['PUB_CACHE'] ??
-    path.context.resolveTildePath('~/.pub-cache');
-
 Future<String> docTestingPackage({
   bool withStats = false,
 }) async {