Skip to content

Commit 5e63ba8

Browse files
authored
Expand category system to all top level items (#1754)
* Flatten non-doc changes * Rebuild test package docs * Update changelog to pass test * Review comments * Rename APIs to Topics * Rebuild test package docs
1 parent 098a3b0 commit 5e63ba8

File tree

429 files changed

+6798
-2613
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

429 files changed

+6798
-2613
lines changed

CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
## 0.21.0-dev.0
2+
* Expand categories to all top level items as well as libraries. (#1681, #1353)
3+
* The categoryOrder option in dartdoc_options.yaml and the command line
4+
is replaced with a more generic "categories" option. See README.md.
5+
16
## 0.20.4
27
* Hide pragma declarations from generated docs (#1726)
38
* Fix problems with lists in markdown not being handled correctly (#172)

README.md

Lines changed: 51 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -102,15 +102,22 @@ generates docs.
102102

103103
```yaml
104104
dartdoc:
105-
categoryOrder: ["First Category", "Second Category"]
105+
categories:
106+
"First Category":
107+
markdown: doc/First.md
108+
name: Awesome
109+
"Second Category":
110+
markdown: doc/Second.md
111+
name: Great
106112
linkTo:
107113
url: "https://my.dartdocumentationsite.org/dev/%v%"
108114
```
109115
110116
Unrecognized options will be ignored. Supported options:
111117
112-
* **categoryOrder**: Specify the order of categories, below, for display in the sidebar and
113-
the package page.
118+
* **categories**: Specify the order of categories. For APIs you'd like to document, specify
119+
the markdown file with `markdown:` to use for the category page. Optionally, rename the
120+
category from the source code into a display name with 'name:'.
114121
* **exclude**: Specify a list of library names to avoid generating docs for,
115122
overriding any specified in include.
116123
* **include**: Specify a list of library names to generate docs for, ignoring all others.
@@ -144,9 +151,11 @@ as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows.
144151

145152
### Categories
146153

147-
You can tag libraries in their documentation with the string `{@category YourCategory}`, and
148-
that will cause the library to appear in a category when showing the sidebar on the Package
149-
and Library pages.
154+
You can tag libraries or top level classes, functions, and variables in their documentation with
155+
the string `{@category YourCategory}`. For libraries, that will cause the library to appear in a
156+
category when showing the sidebar on the Package and Library pages. For other types of objects,
157+
the `{@category}` will be shown with a link to the category page if specified in
158+
dartdoc_options.yaml, as above.
150159

151160
```dart
152161
/// Here is my library.
@@ -155,6 +164,42 @@ and Library pages.
155164
library my_library;
156165
```
157166

167+
#### Other category tags and categories.json
168+
169+
A file `categories.json` will be generated at the top level of the documentation tree with
170+
information about categories collected from objects in the source tree. The directives
171+
`@category`, `@subCategory`, `@image`, and `@samples` are understood and saved into this json.
172+
Future versions of dartdoc may make direct use of the image and samples tags.
173+
174+
As an example, if we document the class Icon in flutter using the following:
175+
176+
```dart
177+
/// {@category Basics}
178+
/// {@category Assets, Images, and Icons}
179+
/// {@subCategory Information displays}
180+
/// {@image <image alt='' src='/images/catalog-widget-placeholder.png'>}
181+
class Icon extends StatelessWidget {}
182+
```
183+
184+
that will result in the following json:
185+
186+
```json
187+
{
188+
"name": "Icon",
189+
"qualifiedName": "widgets.Icon",
190+
"href": "widgets/Icon-class.html",
191+
"type": "class",
192+
"categories": [
193+
"Assets, Images, and Icons",
194+
"Basics"
195+
],
196+
"subcategories": [
197+
"Information displays"
198+
],
199+
"image": "<image alt='' src='/images/catalog-widget-placeholder.png'>"
200+
}
201+
```
202+
158203
### Animations
159204

160205
You can specify links to videos inline that will be handled with a simple HTML5 player:

analysis_options.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ analyzer:
1111
- 'testing/test_package_export_error/**'
1212
linter:
1313
rules:
14+
- always_declare_return_types
1415
- annotate_overrides
1516
- avoid_init_to_null
1617
- directives_ordering

bin/dartdoc.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Future<List<DartdocOption>> createDartdocProgramOptions() async {
3333

3434
/// Analyzes Dart files and generates a representation of included libraries,
3535
/// classes, and members. Uses the current directory to look for libraries.
36-
main(List<String> arguments) async {
36+
void main(List<String> arguments) async {
3737
DartdocOptionSet optionSet =
3838
await DartdocOptionSet.fromOptionGenerators('dartdoc', [
3939
createDartdocOptions,

lib/dartdoc.dart

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,8 @@ class Dartdoc extends PackageBuilder {
6666

6767
/// An asynchronous factory method that builds Dartdoc's file writers
6868
/// and returns a Dartdoc object with them.
69-
static withDefaultGenerators(DartdocGeneratorOptionContext config) async {
69+
static Future<Dartdoc> withDefaultGenerators(
70+
DartdocGeneratorOptionContext config) async {
7071
List<Generator> generators = await initGenerators(config);
7172
return new Dartdoc._(config, generators);
7273
}
@@ -259,7 +260,7 @@ class Dartdoc extends PackageBuilder {
259260
} else {
260261
// Error messages are orphaned by design and do not appear in the search
261262
// index.
262-
if (relativeFullPath != '__404error.html') {
263+
if (<String>['__404error.html', 'categories.json'].contains(fullPath)) {
263264
_warn(packageGraph, PackageWarning.orphanedFile, fullPath,
264265
normalOrigin);
265266
}

lib/resources/styles.css

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,55 @@ dl dt.callable .name {
394394
text-decoration: line-through;
395395
}
396396

397+
.category.linked {
398+
font-weight: bold;
399+
opacity: 1;
400+
}
401+
402+
/* Colors for category based on categoryOrder in dartdoc_options.config. */
403+
.category.cp-0 {
404+
background-color: #54b7c4
405+
}
406+
407+
.category.cp-1 {
408+
background-color: #54c47f
409+
}
410+
411+
.category.cp-2 {
412+
background-color: #c4c254
413+
}
414+
415+
.category.cp-3 {
416+
background-color: #c49f54
417+
}
418+
419+
.category.cp-4 {
420+
background-color: #c45465
421+
}
422+
423+
.category.cp-5 {
424+
background-color: #c454c4
425+
}
426+
427+
.category a {
428+
color: white;
429+
}
430+
431+
.category {
432+
vertical-align: text-top;
433+
padding: 4px;
434+
font-size: 12px;
435+
border-radius: 4px;
436+
background-color: #B6B6B6;
437+
text-transform: uppercase;
438+
color: white;
439+
opacity: .5;
440+
}
441+
442+
h1 .category {
443+
vertical-align: middle;
444+
}
445+
397446
p.firstline {
398447
font-weight: bold;
399448
}

0 commit comments

Comments
 (0)