Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[api-documenter] ExperimentalYamlDocumenter suggestions #1831

Open
1 of 3 tasks
rbuckton opened this issue Apr 14, 2020 · 2 comments
Open
1 of 3 tasks

[api-documenter] ExperimentalYamlDocumenter suggestions #1831

rbuckton opened this issue Apr 14, 2020 · 2 comments

Comments

@rbuckton
Copy link
Member

Is this a feature or a bug?

  • Feature
  • Bug
  • Discussion/Suggestion

While I know that ExperimentalYamlDocumenter is an experimental feature, I have some suggestions and concerns about its design:

  • @docCategory (or whatever you name it via "categoryInlineTag") doesn't make much sense as an inline tag. A block tag seems like a better fit.
  • There isn't a recognized @docCategory-like tag in the standard tsdoc set of tags and it's not obvious how to register it or configure tsdoc when running the api-documenter CLI.
  • I'd like more control over categorization:
    • Ability to synthesize category overview pages similar to packages/namespaces (currently all items are still added to the package's main .yml file)
    • Category definitions should be by uid/DeclarationReference or some other mechanism, not name. I might want to have two nested categories with the same name.
    • Consider a configuration option to define a doc tag for types that should be elided, i.e.,"noDocumentationTag": "ignore" and /** @ignore */ ...
    • Consider adding category matching rules, i.e.:
      { "name": "Foo Classes", "categoryItems": {
        "include": [
          { "files": ["foo/**/*.ts"], "kind": "Class" },
        ]
      } }
  • Consider using metadata or a custom field in the TOC item itself rather than a side-table in the config like nonEmptyCategoryNodeNames. Its easier to write a custom config when the effects that apply to a TOC item are local to the TOC item. For example:
    { "tableOfContents": {
      "tocConfig": {
        "items": [
          { "name": "API Reference", "items": [
            { "name": "Classes", "categoryId": "Class" },
            { "name": "Interfaces", "categoryId": "Interface" },
          ] }
        ]
      }
    } }
    /** @category Class */
    export class Foo { }
  • Consider allowing the TOC to be defined in YAML as well as JSON. This would be especially handy for folks working with both api-documenter and docfx as they may likely have other toc.yml files they are already working with and it would be more convenient to author using a single syntax vs. jumping back and forth between JSON and YAML syntax rules.
@octogonz
Copy link
Collaborator

  • @docCategory (or whatever you name it via "categoryInlineTag") doesn't make much sense as an inline tag. A block tag seems like a better fit.

In the current design of TSDoc, block tags cannot have parameters. This is a general issue that affects many other tags such as @inheritDoc. If we want to change that, we should discuss it in a TSDoc issue.

  • There isn't a recognized @docCategory-like tag in the standard tsdoc set of tags and it's not obvious how to register it or configure tsdoc when running the api-documenter CLI.

We recently added a tsdoc-config.json config file that allows non-standard TSDoc tags to be defined. The ESLint plugin already supports it. The plan for API Extractor to support it as well, and model its own non-standard tags (e.g. @betaDocumentation) in a base config that the project's tsdoc-config.json config can extend using the "extends" field.

This work started in PR #1628 but stalled because the original reporter found a workaround that unblocked them. It's not a lot of work to finish it, though.

The ExperimentalYamlDocumenter was designed by @Vitalius1 based on a specific set of TOC requirements for the Fabric project. I can ask his team if they can provide more detail.

I'd like more control over categorization:

The rest of your suggests all seem like good ideas to me. 👍👍 The idea behind ExperimentalYamlDocumenter was to start beefing up API Documenter to be a full-featured documentation tool (whereas in the past it was trying to be a minimal "code sample" that people could fork and customize).

You could start by proposing improvements to the api-documenter.json schema that show how an end user would enable/configure your features. That user interface is the most interesting design question. The underlying implementation often turns out to be quick+easy.

@Vitalius1
Copy link
Contributor

My team has moved to a different team and no longer maintains the documentation project. We have set it on auto-update that runs every morning and so far all good. The implementation of the ExperimentalYamlDocumenter derived mostly from what the Fabric api.json files were providing at that moment. We have pinned the version of api-documenter in that project so no further changes to the api-documenter would break the automated docs update.

As far who is going to own the Fabric docs on docs.microsoft portal, honestly we never came to an agreement. Perhaps @KevinTCoughlin could talk to this as he moved to the SPFx team and as far as I remember the main push for this project was to provide Fabric documentation to Sharepoint third party devs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: AE/AD
Development

No branches or pull requests

3 participants