atlassian-typedoc-dac-plugin

Typedoc DAC Plugin

A typedoc plugin that generates files links in a structure that is friendly for deployment to DAC. Based on the typedoc-plugin-markdown.

Getting Started

Install Typedoc and typedoc-dac-plugin

yarn add typedoc @atlassian/typedoc-dac-plugin

If you're in atlassian frontend you can run this command from your package:

bolt add typedoc @atlassian/typedoc-dac-plugin

###Configure Typedoc

To configure typedoc it's recommended you use a typedoc.json in the root of our package like this:

{
  "entryPoints": ["./test/test-module-one/index.ts", "./test/test-module-two/index.ts"],
  "out": "test/docs",
  "plugin": ["@atlassian/typedoc-dac-plugin"],
  "baseUrl": "cloud/tool/my-docs",
  "dacJsonFileOutput": "test/docs/data/typedoc-dac-plugin-dac.json",
  "baseJsonFile": "test/base-docs-data.json",
  "dacSubcategory": "Client API"
  "projectName": "My Library",
  "generateSeperateKindFilesFor": ["Class"],
  "exampleData": {
    "componentId": "stub-component-id"
  }
}

• entryPoints: Typedoc supports scanning an entire directory for entry points, however for best results with DAC it's best to seperate your modules and declare your submodule entry points (see the test/ directory combined with the typedoc.json in this repo for a good example of how this would work.)
• out: where your docs will be generated
• plugin: you only need to specify this plugin for it to work, you can see the typedoc website for more plugins if you want.
• baseUrl: set this to the base URL for your DAC docs, you would have generated this when you created your DAC docset. Since DAC url routes and directory structure are tightly coupled, this plugin generates files in a directory structure that reflects the base URL
• dacJsonFileOutput: set this to where you'd like your DAC navigation file to be output. If this is not set the plugin will not generate a JSON file for the case where you don't want it to.
• baseJsonFile: The plugin accepts a base file as input to generating the DAC Navigation json file, this is for the case where you need to modify any of the top level items or if you have items in addition to the generated ones.
• dacSubcategory: The title of the subcategory to put all the API docs under
• projectName: The name of the project, appears in the index file of the documentation Note: you can also pass these options in as CLI parameters, however the typedoc.json file is recommended.
• generateSeperateKindFilesFor: Every reflection kind included in this list will get a separate page for each type. For example, if you include 'Class' in this list, you will get different pages for each class defined. If you don't include it, one page of all the classes will be generated.
• exampleData: The keys are properties in method inputs and the values are default values that will be set.

Then this run command to generate your docs:

yarn typedoc

Currently the plugin generates files in a flat structure and assumes you want your entire module inside a sub-category. DAC supports at most one level of nesting, if you'd like to add support for this please contact @bewong

Troubleshooting

I get an Unable to locate entry point warning when generating my docs

Make sure your entry points are being picked up by typescript. This probably means you need to add something to the includes property inside tsconfig.json.

Developing typdoc-dac-plugin

Testing doc generation

The repo has a sample module setup under ./test and an example setup of typedoc.json. To generate the docs based using the plugin you need to build the plugin first and then run typedoc. The test-generate command takes care of both for you:

yarn test-generate

Existing bugs

• Only supports project types, if a single entry point file is passed in, it won't generate any docs. Last working version for single entry points is 0.0.22.
• When generating example input for a method, indexed access only works when the index type is a primitive type. Default behavior just returns without generating an example for that parameter.
• When generating example input for a method, nested generics can't be evaluated. Default behavior just returns without generating the example for that parameter.