dart-lang/dartdoc

Have an option to generate docs without categories

Opened this issue · 4 comments

HosseinYousefi commented

Currently in order to generate general docs about the usage of a package, we're using categories. These categories are then generated as "topics" only if we actually use them inside the doc comments like {@category xyz}. It would be nice if we have an option to have general docs that we can add as .md files by adding them to dartdoc_options.yaml without specifying them inside the source as well.

cc @jonasfj

srawlins commented

Thanks for filing a bug! Is this the same as #1096?

HosseinYousefi commented

It is similar. We could use the same category mechanism as far as I'm concerned in this issue without having to manually add all the categories to the main library for example:

/// {@category foo}
/// {@category bar}
library;

There is a showUndocumentedCategories option but that doesn't do this.

sigurdm commented

I agree this would be nice!

jonasfj commented

Currently, categories is a thing in dartdoc_options.yaml, but they end up as "Topics" in the generated output.

Maybe, instead of having categories in dartdoc_options.yaml, we should make something like:

topics:
- name: calling-foo                        # Gives rise to: /topics/calling-foo.html
  title: "Reliably calling foo"            # title used as display name in links / menu
  markdown: doc/reliably_calling_foo.md    # (optional) markdown file for the page
- name: working-with-foo
  title: "Functions working with foo"
  markdown: doc/working_with_foo.md
  category: foo-functions                  # (optional) name of category for tagging top-level elements

So that we can specify "topics" and a topic can optionally have:

  • a markdown page, and/or,
  • a category name (which can be used in {@category ...} references.

In the future we could expand with other properties, of the top of my head I could imagine we'd want:

  • hidden: true | false, to hide pages / categories not ready yet,
  • deprecated: "message", to hide pages no longer relevant,
  • redirect: "other-topic-name", for when a topic has been renamed,
  • topics: ..., for sub-topics (if we ever want to allow that).

We could also all the concept for "pages".

Before we go ahead and do something like this, we'd have to find out if anyone is using the {@subcategory annotation and to what extend we'd want to support that. As well, as if we want to maintain the weird behavior when using {@category tags on library; directives.

  • 👍1