Support custom categories for libraries within a package – and the SDK

[kevmoo]

Allow organizing the libraries (on the left side of nav) into custom categories

Blocking dart-lang/sdk#32297

[jcollins-g]

marking as P2 based on dartdoc triage priority (enhancements considered important but with no data indicating they are a big win)

[kevmoo]

I'd argue for P1 just because we are moving some dart: apis from core to VM – mirrors and isolates – and we want to help folks understand where they can be used!

[jcollins-g]

Didn't realize/see this was blocking a P1 bug on the SDK side. Agree then with prioritization: moving to P1 and will address after strong mode changes land.

[kevmoo]

Thank you!

…

On Mon, Feb 26, 2018 at 9:37 AM, jcollins-g ***@***.***> wrote: Didn't realize this was blocking a P1 bug on the SDK side. Agree then with prioritization: moving to P1 and will address after strong mode changes land. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1610 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABCigqwRIESHFijWLA84TW6l_kCDGFsks5tYuvJgaJpZM4SRbfj> .

[jcollins-g]

@kevmoo Just to let you know I haven't forgotten this. With #1625 out of the way, now working on a steel thread through dartdoc to make dartdoc_options.yaml real. But before I get much further, I'll outline the planned outcome:

dartdoc_options.yaml will understand (for now) exactly two fields, one for listing the subcategorization, and another for sorting the subcategories.

Then we drop a dartdoc_options.yaml into the SDK like so:

dartdoc:
  subCategoryOrder: ['VM', 'Web']
  subCategories:
    VM: ['dart:io', 'dart:cli']
    Web:
      - 'dart:html'
      - 'dart:indexed_db'
      - 'dart:js'
      - 'dart:js_util'
      - 'dart:svg'
      - 'dart:web_audio'
      - 'dart:web_gl'
      - 'dart:web_sql'

Dartdoc will show uncategorized items in the sidebar first, then will organize the others as listed under subheadings.

[kevmoo]

Ack. Thanks!

…

On Wed, Mar 14, 2018 at 2:35 PM jcollins-g ***@***.***> wrote: @kevmoo <https://github.com/kevmoo> Just to let you know I haven't forgotten this. With #1625 <#1625> out of the way, now working on a steel thread through dartdoc to make dartdoc_options.yaml real. But before I get much further, I'll outline the planned outcome: dartdoc_options.yaml will understand (for now) exactly two fields, one for listing the subcategorization, and another for sorting the subcategories. Then we drop a dartdoc_options.yaml into the SDK like so: dartdoc: categoryOrder: ['VM', 'Web'] categories: VM: ['dart:io', 'dart:cli'] Web: - 'dart:html' - 'dart:indexed_db' - 'dart:js' - 'dart:js_util' - 'dart:svg' - 'dart:web_audio' - 'dart:web_gl' - 'dart:web_sql' Dartdoc will show uncategorized items in the sidebar first, then will organize the others as listed under subheadings. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1610 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABCitmYGRKbp6q5Ttls66Y3UX1Uw_9mks5teY0MgaJpZM4SRbfj> .

[jcollins-g]

This is now close enough for screenshots:

No PR yet (blocked by #1639) but I uploaded the branch for experimentation: https://github.com/dart-lang/dartdoc/tree/dartdoc-categories.

The new version requires a {@category VM} tag in the library documentation for libraries you want to tag. This is more scalable and fits better with the need described in #1353.

[kevmoo]

Woo hoo! (just move mirrors and isolate to VM) :-D

…

On Tue, Mar 20, 2018 at 3:23 PM jcollins-g ***@***.***> wrote: This is now close enough for screenshots: [image: screenshot from 2018-03-20 15-19-41] <https://user-images.githubusercontent.com/14116827/37685847-3f34c478-2c52-11e8-82b9-6b1485a5a05d.png> No PR yet (blocked by #1639 <#1639>) but I uploaded the branch for experimentation: https://github.com/dart-lang/dartdoc/tree/dartdoc-categories. The new version requires a ***@***.*** VM} tag in the library documentation for libraries you want to tag. This is more scalable and fits better with the need described in #1353 <#1353>. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1610 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABCin0zNC4PQ4M3sVeluECU2IkUnciVks5tgYFQgaJpZM4SRbfj> .

[devoncarew]

🎆 !

You might consider adding a Core category for everything not in VM and Web; that would help the different libraries had the same indent.