diff --git a/README.md b/README.md index 2291413e94..4dd7677f59 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,34 @@ authoring doc comments for Dart with `dartdoc`. ## Advanced features +### dartdoc_options.yaml + +Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc +generates docs. + +```yaml +dartdoc: + categoryOrder: ["First Category", "Second Category"] + +``` +For now, there's only one option: + + * **categoryOrder**: Specify the order of categories, below, for display in the sidebar and + the package page. + +### Categories + +You can tag libraries in their documentation with the string `{@category YourCategory}`, and +that will cause the library to appear in a category when showing the sidebar on the Package +and Library pages. + +```dart +/// Here is my library. +/// +/// {@category Amazing} +library my_library; +``` + ### Macros You can specify "macros", i.e. reusable pieces of documentation. For that, first specify a template diff --git a/bin/dartdoc.dart b/bin/dartdoc.dart index b8d06d555f..459049f0dd 100644 --- a/bin/dartdoc.dart +++ b/bin/dartdoc.dart @@ -192,7 +192,8 @@ main(List arguments) async { PackageMeta packageMeta = new PackageMeta.fromDir(inputDir); if (packageMeta == null) { - stderr.writeln(' fatal error: Unable to generate documentation: no pubspec.yaml found'); + stderr.writeln( + ' fatal error: Unable to generate documentation: no pubspec.yaml found'); exit(1); } @@ -212,7 +213,6 @@ main(List arguments) async { } } - logInfo("Generating documentation for '${packageMeta}' into " "${outputDir.absolute.path}${Platform.pathSeparator}"); @@ -221,7 +221,6 @@ main(List arguments) async { footerFilePaths: footerFilePaths, footerTextFilePaths: footerTextFilePaths, faviconPath: args['favicon'], - displayAsPackages: args['use-categories'], prettyIndexJson: args['pretty-index-json']); for (var generator in generators) { @@ -311,10 +310,8 @@ ArgParser _createArgsParser() { parser.addFlag('show-progress', help: 'Display progress indications to console stdout', negatable: false); parser.addOption('sdk-readme', - help: - 'Path to the SDK description file. Deprecated (ignored)'); - parser.addOption('input', - help: 'Path to source directory.'); + help: 'Path to the SDK description file. Deprecated (ignored)'); + parser.addOption('input', help: 'Path to source directory.'); parser.addOption('output', help: 'Path to output directory.', defaultsTo: defaultOutDir); parser.addMultiOption('header', @@ -349,22 +346,18 @@ ArgParser _createArgsParser() { help: 'A path to a favicon for the generated docs.'); parser.addFlag('use-categories', help: - 'Group libraries from the same package in the libraries sidebar. (deprecated, replaced by display-as-packages)', - negatable: false, - defaultsTo: false); - parser.addFlag('display-as-packages', - help: 'Group libraries from the same package in the libraries sidebar.', + 'Group libraries from the same package in the libraries sidebar. (deprecated, ignored)', negatable: false, defaultsTo: false); parser.addMultiOption('category-order', help: - 'A list of package names to place first when --display-as-packages is ' - 'set. Unmentioned categories are sorted after these. (deprecated, replaced by package-order)', + 'A list of package names to place first when grouping libraries in packages. ' + 'Unmentioned categories are sorted after these. (deprecated, replaced by package-order)', splitCommas: true); parser.addMultiOption('package-order', help: - 'A list of package names to place first when --display-as-packages is ' - 'set. Unmentioned categories are sorted after these.', + 'A list of package names to place first when grouping libraries in packages. ' + 'Unmentioned categories are sorted after these.', splitCommas: true); parser.addFlag('auto-include-dependencies', help: diff --git a/lib/dartdoc.dart b/lib/dartdoc.dart index 6c169c6401..bdacf91fd1 100644 --- a/lib/dartdoc.dart +++ b/lib/dartdoc.dart @@ -46,14 +46,12 @@ Future> initGenerators(String url, String relCanonicalPrefix, List footerFilePaths, List footerTextFilePaths, String faviconPath, - bool displayAsPackages: false, bool prettyIndexJson: false}) async { var options = new HtmlGeneratorOptions( url: url, relCanonicalPrefix: relCanonicalPrefix, toolVersion: version, faviconPath: faviconPath, - displayAsPackages: displayAsPackages, prettyIndexJson: prettyIndexJson); return [ diff --git a/lib/resources/styles.css b/lib/resources/styles.css index bd1fc4e69f..ade56f4653 100644 --- a/lib/resources/styles.css +++ b/lib/resources/styles.css @@ -630,6 +630,19 @@ ul.subnav li:last-of-type { padding-top: 25px; } +.sidebar ol li.section-subtitle a { + color: inherit; +} + +.sidebar ol li.section-subtitle { + font-weight: 400; + text-transform: uppercase; +} + +.sidebar ol li.section-subitem { + margin-left: 12px; +} + .sidebar ol li:first-child { padding-top: 0; margin-top: 0; diff --git a/lib/src/html/html_generator.dart b/lib/src/html/html_generator.dart index 012eda0539..4febcc21bd 100644 --- a/lib/src/html/html_generator.dart +++ b/lib/src/html/html_generator.dart @@ -115,9 +115,6 @@ class HtmlGeneratorOptions implements HtmlOptions { final String faviconPath; final bool prettyIndexJson; - @override - final bool displayAsPackages; - @override final String relCanonicalPrefix; @@ -129,7 +126,6 @@ class HtmlGeneratorOptions implements HtmlOptions { this.relCanonicalPrefix, this.faviconPath, String toolVersion, - this.displayAsPackages: false, this.prettyIndexJson: false}) : this.toolVersion = toolVersion ?? 'unknown'; } diff --git a/lib/src/html/template_data.dart b/lib/src/html/template_data.dart index badb39a22b..02134f00dd 100644 --- a/lib/src/html/template_data.dart +++ b/lib/src/html/template_data.dart @@ -7,7 +7,6 @@ import '../model.dart'; abstract class HtmlOptions { String get relCanonicalPrefix; String get toolVersion; - bool get displayAsPackages; } class Subnav { @@ -63,7 +62,6 @@ abstract class TemplateData { T get self; String get version => htmlOptions.toolVersion; String get relCanonicalPrefix => htmlOptions.relCanonicalPrefix; - bool get displayAsPackages => htmlOptions.displayAsPackages; Iterable getSubNavItems() => []; @@ -113,7 +111,7 @@ class PackageTemplateData extends TemplateData { String get homepage => packageGraph.homepage; @override - String get kind => (displayAsPackages || packageGraph.isSdk) ? '' : 'package'; + String get kind => packageGraph.kind; /// `null` for packages because they are at the root – not needed @override diff --git a/lib/src/html/templates.dart b/lib/src/html/templates.dart index d84e4d6b31..446edcf78f 100644 --- a/lib/src/html/templates.dart +++ b/lib/src/html/templates.dart @@ -20,6 +20,8 @@ const _partials = const [ 'constant', 'footer', 'head', + 'library', + 'packages', 'property', 'features', 'documentation', diff --git a/lib/src/model.dart b/lib/src/model.dart index a1d0279eaa..1be1c5e8c3 100644 --- a/lib/src/model.dart +++ b/lib/src/model.dart @@ -1172,6 +1172,34 @@ abstract class Documentable extends Nameable { bool get isDocumented; } +/// Mixin implementing dartdoc categorization for ModelElements. +abstract class Categorization implements ModelElement { + @override + String _buildDocumentationLocal() { + _rawDocs = super._buildDocumentationLocal(); + _rawDocs = _stripAndSetDartdocCategory(_rawDocs); + return _rawDocs; + } + + /// Parse {@category ...} in API comments and store the category in + /// the [_categoryName] variable. + String _stripAndSetDartdocCategory(String rawDocs) { + final categoryRegexp = + new RegExp(r'[ ]*{@category (.+?)}[ ]*\n?', multiLine: true); + return rawDocs.replaceAllMapped(categoryRegexp, (match) { + _categoryName = match[1].trim(); + return ''; + }); + } + + String _categoryName; + String get categoryName { + // TODO(jcollins-g): avoid side-effect dependency + if (_categoryName == null) documentationLocal; + return _categoryName; + } +} + /// Classes extending this class have canonicalization support in Dartdoc. abstract class Canonicalization extends Object with Locatable @@ -1698,7 +1726,7 @@ abstract class GetterSetterCombo implements ModelElement { Accessor get setter; } -class Library extends ModelElement { +class Library extends ModelElement with Categorization { @override final PackageGraph packageGraph; @@ -2174,9 +2202,10 @@ class Library extends ModelElement { return name; } - static PackageMeta getPackageMeta(LibraryElement element) { + static PackageMeta getPackageMeta(Element element) { String sourcePath = element.source.fullName; - return new PackageMeta.fromDir(new File(pathLib.canonicalize(sourcePath)).parent); + return new PackageMeta.fromDir( + new File(pathLib.canonicalize(sourcePath)).parent); } static String getLibraryName(LibraryElement element) { @@ -3728,8 +3757,6 @@ class Operator extends Method { String get typeName => 'operator'; } -// TODO(jcollins-g): Break [Package] out into a real single-package only -// class, and a container class for a set of packages. class PackageGraph extends Canonicalization with Nameable, Warnable { // All library objects related to this package; a superset of _libraries. final Map allLibraries = new Map(); @@ -4046,20 +4073,27 @@ class PackageGraph extends Canonicalization with Nameable, Warnable { return locatable.fullyQualifiedName.replaceFirst(':', '-'); } + bool get hasMultiplePackages => publicPackages.length > 1; + + List _publicPackages; List get publicPackages { - List _publicPackages; - // Help the user if they pass us a package that doesn't exist. - for (String packageName in config.packageOrder) { - if (!packages.containsKey(packageName)) - warnOnElement(null, PackageWarning.packageOrderGivesMissingPackageName, - message: "${packageName}, packages: ${packages.keys.join(',')}"); + if (_publicPackages == null) { + // Help the user if they pass us a package that doesn't exist. + for (String packageName in config.packageOrder) { + if (!packages.containsKey(packageName)) + warnOnElement( + null, PackageWarning.packageOrderGivesMissingPackageName, + message: "${packageName}, packages: ${packages.keys.join(',')}"); + } + _publicPackages = packages.values.where((p) => p.isPublic).toList() + ..sort(); } - _publicPackages = packages.values - .where((p) => p.libraries.any((l) => l.isPublic)) - .toList(); - return _publicPackages..sort(); + return _publicPackages; } + // Use only in testing. + void resetPublicPackages() => _publicPackages = null; + Map> _libraryElementReexportedBy = new Map(); void _tagReexportsFor( final Library tll, final LibraryElement libraryElement) { @@ -4183,8 +4217,7 @@ class PackageGraph extends Canonicalization with Nameable, Warnable { @override String get name => packageMeta.name; - String get kind => - (packageGraph.isSdk) ? 'SDK' : 'package'; + String get kind => (packageGraph.isSdk) ? 'SDK' : 'package'; @override String get oneLineDoc => ''; @@ -4461,14 +4494,118 @@ class PackageGraph extends Canonicalization with Nameable, Warnable { } } -class Package implements Comparable { - final String name; - - // Initialized by [PackageGraph.PackageGraph]. +/// A set of libraries, initialized after construction by accessing [_libraries]. +/// Do not call any methods or members excepting [_libraries] and [name] before +/// finishing initialization of a [LibraryContainer]. +abstract class LibraryContainer extends Nameable { final List _libraries = []; - PackageGraph packageGraph; + PackageGraph get packageGraph; + + List get libraries => _libraries; + Iterable get publicLibraries => filterNonPublic(libraries); + + @override + String toString() => name; +} + +/// A category is a subcategory of a package, containing libraries tagged +/// with a @category identifier. Comparable so it can be sorted according to +/// [dartdocOptions.categoryOrder]. +class Category extends LibraryContainer implements Comparable { + /// All libraries in [libraries] must come from [package]. + Package package; + DartdocOptions dartdocOptions; + String _name; - Package(this.name, this.packageGraph); + Category(this._name, this.package, this.dartdocOptions); + + @override + String get name => _name; + + /// Returns: + /// -1 if this category is listed in categoryOrder. + /// 0 if this category is named the same as the package. + /// 1 if this group has a name that contains the name of the package. + /// 2 otherwise. + int get _group { + if (dartdocOptions.categoryOrder.contains(name)) return -1; + if (name.toLowerCase() == package.name.toLowerCase()) return 0; + if (name.toLowerCase().contains(package.name.toLowerCase())) return 1; + return 2; + } + + @override + int compareTo(Category other) { + if (_group == other._group) { + if (_group == -1) { + return Comparable.compare(dartdocOptions.categoryOrder.indexOf(name), + dartdocOptions.categoryOrder.indexOf(other.name)); + } else { + return name.toLowerCase().compareTo(other.name.toLowerCase()); + } + } + return Comparable.compare(_group, other._group); + } + + @override + PackageGraph get packageGraph => package.packageGraph; +} + +/// A [LibraryContainer] that contains [Library] objects related to a particular +/// package. +class Package extends LibraryContainer implements Comparable, Privacy { + String _name; + PackageGraph _packageGraph; + + final Map _nameToCategory = {}; + Package(this._name, this._packageGraph); + + /// Return true if the code has defined non-default categories for libraries + /// in this package. + bool get hasCategories => categories.isNotEmpty; + + LibraryContainer get defaultCategory => nameToCategory[null]; + + bool _isPublic; + @override + bool get isPublic { + if (_isPublic == null) _isPublic = libraries.any((l) => l.isPublic); + return _isPublic; + } + + @override + String get name => _name; + + @override + PackageGraph get packageGraph => _packageGraph; + + // Workaround for mustache4dart issue where templates do not recognize + // inherited properties as being in-context. + @override + List get publicLibraries => super.publicLibraries; + + /// A map of category name to the category itself. + Map get nameToCategory { + if (_nameToCategory.isEmpty) { + _nameToCategory[null] = new Category(null, this, dartdocOptions); + for (Library lib in libraries) { + String category = lib.categoryName; + _nameToCategory.putIfAbsent( + category, () => new Category(category, this, dartdocOptions)); + _nameToCategory[category]._libraries.add(lib); + } + } + return _nameToCategory; + } + + List _categories; + List get categories { + if (_categories == null) { + _categories = nameToCategory.values.where((c) => c.name != null).toList() + ..sort(); + } + return _categories; + } DartdocOptions _dartdocOptions; DartdocOptions get dartdocOptions { @@ -4478,6 +4615,10 @@ class Package implements Comparable { return _dartdocOptions; } + /// Is this the package at the top of the list? We display the first + /// package specially (with "Libraries" rather than the package name). + bool get isFirstPackage => identical(packageGraph.publicPackages.first, this); + bool get isSdk => packageMeta.isSdk; String _packagePath; @@ -4503,10 +4644,6 @@ class Package implements Comparable { return _packagePath; } - List get libraries => _libraries; - - Iterable get publicLibraries => filterNonPublic(libraries); - PackageMeta _packageMeta; // TODO(jcollins-g): packageMeta should be passed in with the object rather // than calculated indirectly from libraries. diff --git a/lib/src/package_meta.dart b/lib/src/package_meta.dart index 12562e4a6e..d85bf26308 100644 --- a/lib/src/package_meta.dart +++ b/lib/src/package_meta.dart @@ -12,7 +12,6 @@ import 'package:yaml/yaml.dart'; import 'logging.dart'; - Map _packageMetaCache = {}; abstract class PackageMeta { @@ -30,7 +29,8 @@ abstract class PackageMeta { if (!_packageMetaCache.containsKey(dir.path)) { PackageMeta packageMeta; // There are pubspec.yaml files inside the SDK. Ignore them. - if (pathLib.isWithin(getSdkDir().absolute.path, dir.path) || getSdkDir().path == dir.path) { + if (pathLib.isWithin(getSdkDir().absolute.path, dir.path) || + getSdkDir().path == dir.path) { packageMeta = new _SdkMeta(getSdkDir()); } else { while (dir.existsSync()) { @@ -178,7 +178,6 @@ class _FilePackageMeta extends PackageMeta { return _changelog; } - /// Returns a list of reasons this package is invalid, or an /// empty list if no reasons found. @override @@ -211,8 +210,7 @@ File _locate(Directory dir, List fileNames) { class _SdkMeta extends PackageMeta { String sdkReadmePath; - _SdkMeta(Directory dir) - : super(dir) { + _SdkMeta(Directory dir) : super(dir) { sdkReadmePath = pathLib.join(dir.path, 'lib', 'api_readme.md'); } diff --git a/lib/templates/_library.html b/lib/templates/_library.html new file mode 100644 index 0000000000..6ef3a260d4 --- /dev/null +++ b/lib/templates/_library.html @@ -0,0 +1,6 @@ +
+ {{{ linkedName }}} +
+
+ {{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}} +
\ No newline at end of file diff --git a/lib/templates/_packages.html b/lib/templates/_packages.html new file mode 100644 index 0000000000..7cc22a4186 --- /dev/null +++ b/lib/templates/_packages.html @@ -0,0 +1,19 @@ +
    + {{#packageGraph.publicPackages}} + {{#isFirstPackage}} +
  1. Libraries
    2. + {{/isFirstPackage}} + {{^isFirstPackage}} +
  2. {{name}}
    3. + {{/isFirstPackage}} + {{#defaultCategory.publicLibraries}} +
  3. {{{linkedName}}}
    4. + {{/defaultCategory.publicLibraries}} + {{#categories}} +
  4. {{name}}
    5. + {{#publicLibraries}} +
  5. {{{linkedName}}}
    6. + {{/publicLibraries}} + {{/categories}} + {{/packageGraph.publicPackages}} +
diff --git a/lib/templates/index.html b/lib/templates/index.html index 0b7ec93e85..326ff6822f 100644 --- a/lib/templates/index.html +++ b/lib/templates/index.html @@ -2,67 +2,35 @@
{{self.name}} {{self.kind}}
- - {{#displayAsPackages}} -
    - {{#packageGraph.publicPackages}} -
  1. {{name}}
    2. - {{#publicLibraries}} -
  2. {{{linkedName}}}
    3. - {{/publicLibraries}} - {{/packageGraph.publicPackages}} -
- {{/displayAsPackages}} - - {{^displayAsPackages}} -
    -
  1. Libraries
    2. - {{#packageGraph.publicLibraries}} -
  2. {{{linkedName}}}
    3. - {{/packageGraph.publicLibraries}} -
- {{/displayAsPackages}} + {{>packages}}
{{#packageGraph}} {{>documentation}} - {{/packageGraph}} - {{#displayAsPackages}} - {{#packageGraph.publicPackages}} + {{#publicPackages}}
-

{{name}}

+ {{#isFirstPackage}} +

Libraries

+ {{/isFirstPackage}} + {{^isFirstPackage}} +

{{name}}

+ {{/isFirstPackage}}
- {{#libraries}} -
- {{{ linkedName }}} -
-
- {{#isDocumented}}{{{ oneLineDoc }}}{{/isDocumented}} -
- {{/libraries}} + {{#defaultCategory.publicLibraries}} + {{>library}} + {{/defaultCategory.publicLibraries}} + {{#categories}} +

{{name}}

+ {{#publicLibraries}} + {{>library}} + {{/publicLibraries}} + {{/categories}}
- {{/packageGraph.publicPackages}} - - {{/displayAsPackages}} - - {{^displayAsPackages}} -
-

Libraries

-
- {{#packageGraph.publicLibraries}} -
- {{{ linkedName }}} -
-
- {{{ oneLineDoc }}} -
- {{/packageGraph.publicLibraries}} -
-
- {{/displayAsPackages}} + {{/publicPackages}} + {{/packageGraph}}
diff --git a/lib/templates/library.html b/lib/templates/library.html index ff4c02f1ad..89e3eee3c9 100644 --- a/lib/templates/library.html +++ b/lib/templates/library.html @@ -2,25 +2,7 @@
{{parent.name}} {{parent.kind}}
- {{#displayAsPackages}} -
    - {{#packageGraph.publicPackages}} -
  1. {{name}}
    2. - {{#publicLibraries}} -
  2. {{{linkedName}}}
    3. - {{/publicLibraries}} - {{/packageGraph.publicPackages}} -
- {{/displayAsPackages}} - - {{^displayAsPackages}} -
    -
  1. Libraries
    2. - {{#packageGraph.publicLibraries}} -
  2. {{{linkedName}}}
    3. - {{/packageGraph.publicLibraries}} -
- {{/displayAsPackages}} + {{>packages}}
diff --git a/test/model_test.dart b/test/model_test.dart index d04a20f478..e4fdef5007 100644 --- a/test/model_test.dart +++ b/test/model_test.dart @@ -24,6 +24,7 @@ void main() { } PackageGraph packageGraph; + PackageGraph packageGraphSmall; PackageGraph ginormousPackageGraph; Library exLibrary; Library fakeLibrary; @@ -34,6 +35,7 @@ void main() { setUpAll(() async { await utils.init(); packageGraph = utils.testPackageGraph; + packageGraphSmall = utils.testPackageGraphSmall; ginormousPackageGraph = utils.testPackageGraphGinormous; exLibrary = packageGraph.libraries.firstWhere((lib) => lib.name == 'ex'); fakeLibrary = @@ -45,10 +47,47 @@ void main() { sdkAsPackageGraph = utils.testPackageGraphSdk; }); + group('Category', () { + test('Verify categories for test_package', () { + expect(packageGraph.publicPackages.length, equals(1)); + expect(packageGraph.publicPackages.first.hasCategories, isTrue); + List packageCategories = + packageGraph.publicPackages.first.categories; + expect(packageCategories.length, equals(3)); + expect(packageCategories.map((c) => c.name).toList(), + orderedEquals(['Real Libraries', 'Unreal', 'Misc'])); + expect(packageCategories.map((c) => c.libraries.length).toList(), + orderedEquals([2, 2, 1])); + expect( + packageGraph + .publicPackages.first.defaultCategory.publicLibraries.length, + equals(3)); + }); + + test('Verify that packages without categories get handled', () { + expect(packageGraphSmall.publicPackages.length, equals(1)); + expect(packageGraphSmall.publicPackages.first.hasCategories, isFalse); + List packageCategories = + packageGraphSmall.publicPackages.first.categories; + expect(packageCategories.length, equals(0)); + expect( + packageGraph + .publicPackages.first.defaultCategory.publicLibraries.length, + equals(3)); + }); + }); + group('Package', () { group('test package', () { setUp(() { setConfig(); + ginormousPackageGraph.resetPublicPackages(); + packageGraph.resetPublicPackages(); + }); + tearDown(() { + setConfig(); + ginormousPackageGraph.resetPublicPackages(); + packageGraph.resetPublicPackages(); }); test('name', () { @@ -233,7 +272,7 @@ void main() { test('has documentation', () { expect(exLibrary.documentation, - 'a library. testing string escaping: `var s = \'a string\'` '); + 'a library. testing string escaping: `var s = \'a string\'` \n'); }); test('has one line docs', () { diff --git a/testing/test_package/dartdoc_options.yaml b/testing/test_package/dartdoc_options.yaml new file mode 100644 index 0000000000..83ad422ac3 --- /dev/null +++ b/testing/test_package/dartdoc_options.yaml @@ -0,0 +1,2 @@ +dartdoc: + categoryOrder: ["Real Libraries", "Unreal"] diff --git a/testing/test_package/lib/css.dart b/testing/test_package/lib/css.dart index 3215fe0b9e..74a68c4cf6 100644 --- a/testing/test_package/lib/css.dart +++ b/testing/test_package/lib/css.dart @@ -1,5 +1,6 @@ /// Testing that a library name doesn't conflict /// with directories created by dartdoc. +/// {@category Other} library css; String theOnlyThingInTheLibrary = 'hello'; diff --git a/testing/test_package/lib/example.dart b/testing/test_package/lib/example.dart index c7664dbb90..91febaa940 100644 --- a/testing/test_package/lib/example.dart +++ b/testing/test_package/lib/example.dart @@ -1,4 +1,5 @@ /// a library. testing string escaping: `var s = 'a string'` +/// {@category Real Libraries} library ex; import 'dart:async'; diff --git a/testing/test_package/lib/fake.dart b/testing/test_package/lib/fake.dart index fd88e32fc8..c8785fe785 100644 --- a/testing/test_package/lib/fake.dart +++ b/testing/test_package/lib/fake.dart @@ -1,5 +1,5 @@ /// # WOW FAKE PACKAGE IS __BEST__ [PACKAGE][pkg] -/// +/// {@category Real Libraries} /// If you don't have this package yet, get it. /// Don't ask questions. /// diff --git a/testing/test_package/lib/reexport_one.dart b/testing/test_package/lib/reexport_one.dart index 609d2986b3..a0698a3e97 100644 --- a/testing/test_package/lib/reexport_one.dart +++ b/testing/test_package/lib/reexport_one.dart @@ -1,5 +1,6 @@ /// {@canonicalFor reexport.somelib.SomeOtherClass} /// {@canonicalFor reexport.somelib.AUnicornClass} +/// {@category Unreal} library reexport_one; export 'src/somelib.dart'; diff --git a/testing/test_package/lib/reexport_two.dart b/testing/test_package/lib/reexport_two.dart index d8fbd053e2..bad819be50 100644 --- a/testing/test_package/lib/reexport_two.dart +++ b/testing/test_package/lib/reexport_two.dart @@ -1,6 +1,7 @@ /// {@canonicalFor reexport.somelib.SomeClass} /// {@canonicalFor reexport.somelib.AUnicornClass} /// {@canonicalFor something.ThatDoesntExist} +/// {@category Unreal} library reexport_two; export 'src/somelib.dart'; diff --git a/testing/test_package/lib/two_exports.dart b/testing/test_package/lib/two_exports.dart index 233d46e6d7..c3e26f3b70 100644 --- a/testing/test_package/lib/two_exports.dart +++ b/testing/test_package/lib/two_exports.dart @@ -1,3 +1,4 @@ +/// {@category Misc} library two_exports; export 'src/base.dart'; diff --git a/testing/test_package_docs/anonymous_library/anonymous_library-library.html b/testing/test_package_docs/anonymous_library/anonymous_library-library.html index 1d4534e6c4..88f41e9451 100644 --- a/testing/test_package_docs/anonymous_library/anonymous_library-library.html +++ b/testing/test_package_docs/anonymous_library/anonymous_library-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/another_anonymous_lib/another_anonymous_lib-library.html b/testing/test_package_docs/another_anonymous_lib/another_anonymous_lib-library.html index 22447b4d92..df4fbbef68 100644 --- a/testing/test_package_docs/another_anonymous_lib/another_anonymous_lib-library.html +++ b/testing/test_package_docs/another_anonymous_lib/another_anonymous_lib-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/code_in_comments/code_in_comments-library.html b/testing/test_package_docs/code_in_comments/code_in_comments-library.html index c6dcd0d8b2..e212de3b2d 100644 --- a/testing/test_package_docs/code_in_comments/code_in_comments-library.html +++ b/testing/test_package_docs/code_in_comments/code_in_comments-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/css/css-library.html b/testing/test_package_docs/css/css-library.html index 35c76a568c..ff38dcce76 100644 --- a/testing/test_package_docs/css/css-library.html +++ b/testing/test_package_docs/css/css-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/ex/ex-library.html b/testing/test_package_docs/ex/ex-library.html index 2b4da0baba..beefc48964 100644 --- a/testing/test_package_docs/ex/ex-library.html +++ b/testing/test_package_docs/ex/ex-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/fake/fake-library.html b/testing/test_package_docs/fake/fake-library.html index 4584ec5038..7be70a412a 100644 --- a/testing/test_package_docs/fake/fake-library.html +++ b/testing/test_package_docs/fake/fake-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/index.html b/testing/test_package_docs/index.html index fe6e70594c..d9b6ac4601 100644 --- a/testing/test_package_docs/index.html +++ b/testing/test_package_docs/index.html @@ -33,21 +33,24 @@
test_package package
- -
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
@@ -97,23 +100,20 @@

Best Package

Be sure to check out other awesome packages on pub.

- -
-

Libraries

-
+
+

Libraries

+
anonymous_library
-
-
+
another_anonymous_lib
-
-
+
code_in_comments
@@ -121,58 +121,58 @@

Libraries

// in Dart! } [...] -
-
- css -
-
- Testing that a library name doesn't conflict -with directories created by dartdoc. -
-
- ex -
-
- a library. testing string escaping: var s = 'a string' -
-
- fake -
-
- WOW FAKE PACKAGE IS BEST PACKAGE [...] -
-
+
is_deprecated
This lib is deprecated. It never had a chance -
-
- reexport_one -
-
- -
-
- reexport_two -
-
- -
+

Real Libraries

+
+ ex +
+
+ a library. testing string escaping: var s = 'a string' +
+ fake +
+
+ WOW FAKE PACKAGE IS BEST PACKAGE [...] +

Unreal

+
+ reexport_one +
+
+ +
+ reexport_two +
+
+ +

Misc

+
+ two_exports +
+
+ +

Other

+
+ css +
+
+ Testing that a library name doesn't conflict +with directories created by dartdoc. +
+
+
+

test_package_imported

+
test_package_imported.main
-
-
- two_exports -
-
- -
-
-
+
+
diff --git a/testing/test_package_docs/is_deprecated/is_deprecated-library.html b/testing/test_package_docs/is_deprecated/is_deprecated-library.html index 906ba22e38..c918e0134d 100644 --- a/testing/test_package_docs/is_deprecated/is_deprecated-library.html +++ b/testing/test_package_docs/is_deprecated/is_deprecated-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/reexport_one/reexport_one-library.html b/testing/test_package_docs/reexport_one/reexport_one-library.html index 12308942a8..baadb44e0f 100644 --- a/testing/test_package_docs/reexport_one/reexport_one-library.html +++ b/testing/test_package_docs/reexport_one/reexport_one-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/reexport_two/reexport_two-library.html b/testing/test_package_docs/reexport_two/reexport_two-library.html index 3bc1b496eb..6355f9bc2a 100644 --- a/testing/test_package_docs/reexport_two/reexport_two-library.html +++ b/testing/test_package_docs/reexport_two/reexport_two-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/static-assets/styles.css b/testing/test_package_docs/static-assets/styles.css index bd1fc4e69f..ade56f4653 100644 --- a/testing/test_package_docs/static-assets/styles.css +++ b/testing/test_package_docs/static-assets/styles.css @@ -630,6 +630,19 @@ ul.subnav li:last-of-type { padding-top: 25px; } +.sidebar ol li.section-subtitle a { + color: inherit; +} + +.sidebar ol li.section-subtitle { + font-weight: 400; + text-transform: uppercase; +} + +.sidebar ol li.section-subitem { + margin-left: 12px; +} + .sidebar ol li:first-child { padding-top: 0; margin-top: 0; diff --git a/testing/test_package_docs/test_package_imported.main/test_package_imported.main-library.html b/testing/test_package_docs/test_package_imported.main/test_package_imported.main-library.html index da267e33a4..f83b769685 100644 --- a/testing/test_package_docs/test_package_imported.main/test_package_imported.main-library.html +++ b/testing/test_package_docs/test_package_imported.main/test_package_imported.main-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main
diff --git a/testing/test_package_docs/two_exports/two_exports-library.html b/testing/test_package_docs/two_exports/two_exports-library.html index ac5e38c0e9..410e513a73 100644 --- a/testing/test_package_docs/two_exports/two_exports-library.html +++ b/testing/test_package_docs/two_exports/two_exports-library.html @@ -36,20 +36,24 @@
test_package package
-
    -
  1. Libraries
    2. -
  2. anonymous_library
    3. -
  3. another_anonymous_lib
    4. -
  4. code_in_comments
    5. -
  5. css
    6. -
  6. ex
    7. -
  7. fake
    8. -
  8. is_deprecated
    9. -
  9. reexport_one
    10. -
  10. reexport_two
    11. -
  11. test_package_imported.main
    12. -
  12. two_exports
    13. +
  13. Libraries
    14. +
  14. anonymous_library
    15. +
  15. another_anonymous_lib
    16. +
  16. code_in_comments
    17. +
  17. is_deprecated
    18. +
  18. Real Libraries
    19. +
  19. ex
    20. +
  20. fake
    21. +
  21. Unreal
    22. +
  22. reexport_one
    23. +
  23. reexport_two
    24. +
  24. Misc
    25. +
  25. two_exports
    26. +
  26. Other
    27. +
  27. css
    28. +
  28. test_package_imported
    29. +
  29. test_package_imported.main