Use _category name_ in the URL, instead of the _category displayName_. (#4031)

Also clarify documentation, to make it a bit more obvious that a
category has two names:
 * _category name_, the thing we reference in source code,
 * _display name_, the thing we display in HTML.

I imagine that the _category name_ lends itself better to be used in a
URL (probably using underscore). And the _display name_ is probably
something using whitespaces (which don't work nearly as well in a URL).

Also correct `name` -> `displayName` in README.

--------------

I don't know if we should make _redirect pages_ for the old URLs. It's
perhaps overkill, since the category feature isn't used by most
packages. Does `api.dart.dev` or `api.flutter.dev` have topic pages?

Author: jonasfj

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;

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>');
     });
   });