tsdoc/api-demo

api-demo

This is a simple code sample that illustrates how to invoke the API for the @microsoft/tsdoc library.

Building and running api-demo (standalone with NPM)

Here's quick instructions to see the api-demo.

This approach will use the latest official release of the @microsoft/tsdoc library. It will NOT symlink to your local build of the library.

1. Install the NPM dependencies for the api-demo project:

   $ cd ./api-demo
   # Note: Be sure to specify "--no-package-lock" to avoid conflicts with Rush
   $ npm install --no-package-lock
   

2. Build the api-demo project like this:

   $ npm run build
   

3. Run the api-demo project:

   The simple demo does not rely on the TypeScript compiler API; instead, it parses the source file directly. It uses the default parser configuration.

   $ npm run simple
   

   The advanced demo invokes the TypeScript compiler and extracts the comment from the AST. It also illustrates how to define custom TSDoc tags using TSDocParserConfiguration.

   $ npm run advanced
   

Building and running api-demo api-demo (using Rush and Yarn)

If you're going to submit a pull request for TSDoc, you will need to use the Rush monorepo manager tool. See Contributing.md for more information.

Rush will link api-demo to use your local build of the @microsoft/tsdoc library, for easy testing/validation.

1. Install the Rush software:

$ npm install -g @microsoft/rush

NOTE: If this command fails because your user account does not have permissions to access NPM's global folder, you may need to fix your NPM configuration.

2. Install dependencies for all projects in the monorepo:

# Run this command in the folder where you cloned the TSDoc repo from GitHub
$ rush install

3. Build all the projects in the monorepo:

$ rush build

You can also build just the api-demo project like this:

$ cd ./api-demo
$ npm run build

4. Run the api-demo project (see above notes for more details):

   $ npm run simple
   $ npm run advanced
   

IMPORTANT: After you run rush install, your repo will be in a "Rush-linked" state, with special symlinks in the node_modules folders. DO NOT run npm install in this state. If you want to go back to working in standalone mode, first run rush unlink && rush purge.