diff --git a/CHANGELOG.md b/CHANGELOG.md index ecbb21a51c..d7dbe2aa8b 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index b49dee1fd7..8db4c56b46 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ 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): @@ -117,13 +117,13 @@ 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 }` 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; ``` diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml index 01513eea5a..0f32c4fac4 100644 --- a/dartdoc_options.yaml +++ b/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%' diff --git a/lib/src/model/category.dart b/lib/src/model/category.dart index 6d3c1d32e2..5008b3ef0e 100644 --- a/lib/src/model/category.dart +++ b/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; diff --git a/pubspec.yaml b/pubspec.yaml index c951c220f7..77c01ca47b 100644 --- a/pubspec.yaml +++ b/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 diff --git a/test/end2end/model_test.dart b/test/end2end/model_test.dart index 6fb5b8b493..331f2f9d56 100644 --- a/test/end2end/model_test.dart +++ b/test/end2end/model_test.dart @@ -720,13 +720,13 @@ void main() async { expect( category.categoryLabel, '' - 'Superb'); + 'Superb'); }); test('CategoryRendererHtml renders linkedName', () { var category = packageGraph.publicPackages.first.categories.first; expect(category.linkedName, - 'Superb'); + 'Superb'); }); });