Git Product home page Git Product logo

api-docs-gen's Introduction

๐Ÿ“” api-docs-gen

Test npm

API Documentation generator from api-extractor doc model

๐Ÿ”จ Requirement

You need to generate doc model with using api-extractor

๐Ÿ’ฟ Installation

npm

$ npm install -g api-docs-gen

yarn

yarn global api-docs-gen

pnpm

pnpm add -g api-docs-gen

๐Ÿš€ Usage

CLI

Usage
  $ api-docs-gen <package1.api.json> <package2.api.json> ...

Options
  --config, -c              configration file
  --output, -o              output dierectory that is markdown contents
  --generateStyle, -g       document generating style, default 'prefix'
                            'prefix': be able to separated with each package name
                            'directory': be able to separated with each package directory
  --tsdocConfig, -t         tsdoc configration file

๐Ÿค API

const path = require('path')
const { genereate, DefaultConfig } = require('api-docs-gen')

// input
const input = [path.resolve(process.cwd(), './package1.api.json')]

// output
const output = path.resolve(process.cwd(), './docs')

// generate API docs with prefixed package name
await generate(input, output, { style: 'prefix', config: DefaultConfig })

About details, See the API References

๐Ÿญ Examples

You can play API docs generation that have multi packages.

You can play with the following command:

$ pnpm example:build # build on each package

$ pnpm example:extract # generate doc model with `api-extractor` on each package

$ pnpm example:gen # genearte API docs with `api-docs-gen`

$ pnpm example:docs # run vuepress

๐Ÿ”– TSDoc custom tags

api-docs-gen allows TSDoc custom tags to be processed using tsdoc-config.

You can make it work from the api-extractor model by specifying tsdoc configration in the --tsdoc-config option as follows:

$ api-docs-gen package1.api.json --tsdoc-config ./tsdoc.json

If you want to output custom tags comment to markdown, you need to implement and configure the custom MarkdownProcessor.

For the MarkdownProcessor, see the API References.

See how to configure it in the following configration.

๐Ÿ”ง Configration

You can fully customize the generation of api docs using the config offered by api-docs-gen.

Here is the schema (typescript type definition) of the config:

// There are two things you need to specify in config
export interface Config {
  // A resolver that resolves references to links in markdown content
  linkReferencer?: ReferenceResolver
  // A processor that generates markdown content
  processor: MarkdownProcessor
}

You can generate customized api docs by specifying these as you define them in your config, and the CLI --config option. api-docs-gen CLI will read docsgen.config.js as default.

api-docs-gen API docs is a TOC included markdown document. To generate the API docs, it use a customized resolver and processor for TOC.

If you want to customize your api docs, these will be helpful.

It's recommended to refer to the API References for customization.

๐Ÿ“œ Changelog

Details changes for each release are documented in the CHANGELOG.md.

โ— Issues

Please make sure to read the Issue Reporting Checklist before opening an issue. Issues not conforming to the guidelines may be closed immediately.

โœ… TODO

Managed with GitHub Projects

ยฉ๏ธ License

MIT

api-docs-gen's People

Contributors

dependabot[bot] avatar kazupon avatar renovate-bot avatar renovate[bot] avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

api-docs-gen's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

  • chore(deps): replace dependency npm-run-all with npm-run-all2 ^5.0.0
  • chore(deps): update dependency @types/node to v20
  • chore(deps): update dependency eslint to v9
  • chore(deps): update pnpm/action-setup action to v3
  • fix(deps): update dependency meow to v13
  • ๐Ÿ” Create all rate-limited PRs at once ๐Ÿ”

Edited/Blocked

These updates have been manually edited so Renovate will no longer make changes. To discard all commits and start over, click on a checkbox.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

Detected dependencies

github-actions
.github/workflows/lint.yml
  • actions/checkout v3
  • pnpm/action-setup v2.4.0
  • actions/setup-node v3
.github/workflows/test.yml
  • actions/checkout v3
  • pnpm/action-setup v2.4.0
  • actions/setup-node v3
npm
package.json
  • @microsoft/api-extractor-model ^7.12.0
  • @microsoft/tsdoc ^0.14.0
  • @microsoft/tsdoc-config ^0.16.0
  • chalk ^4.1.1
  • debug ^4.3.3
  • meow ^9.0.0
  • @kazupon/lerna-changelog ^4.3.0
  • @microsoft/api-extractor ^7.18.21
  • @types/debug ^4.1.5
  • @types/jest ^27.0.0
  • @types/node ^16.11.0
  • @typescript-eslint/eslint-plugin ^5.5.0
  • @typescript-eslint/parser ^5.5.0
  • eslint ^8.4.0
  • eslint-config-prettier ^8.3.0
  • eslint-plugin-prettier ^4.0.0
  • jest ^27.0.0
  • jest-watch-typeahead ^1.0.0
  • npm-run-all ^4.1.5
  • opener ^1.5.2
  • prettier ^2.5.0
  • shipjs ^0.26.0
  • ts-jest ^27.0.0
  • typescript ^4.5.2
  • vuepress ^1.8.2
  • node >= 12
  • typescript ^4.5.2
  • @microsoft/api-extractor ^7.18.21

  • Check this box to trigger a request for Renovate to run again on this repository

Fatal error when resolving {@link} expressions.

Example:

/**
 * A
 *
 * @public
 */
export type A = string;

/**
 * {@link A}
 *
 * @public
 */
export type B = number;

Process will exit with code 1, and throw this exception:

TypeError: resolver is not a function
    at getDocSectionContent (/home/jsamr/tmp/api-docs-gen/lib/processor/utils.js:445:46)
    at Object.buildTypeAliasContent (/home/jsamr/tmp/api-docs-gen/lib/processor/utils.js:325:9)
    at buildContents (/home/jsamr/tmp/api-docs-gen/lib/processor/toc.js:78:29)
    at build (/home/jsamr/tmp/api-docs-gen/lib/processor/toc.js:29:9)
    at Object.process [as processor] (/home/jsamr/tmp/api-docs-gen/lib/processor/toc.js:91:12)
    at Object.generate (/home/jsamr/tmp/api-docs-gen/lib/generator.js:30:29)
    at /home/jsamr/tmp/api-docs-gen/lib/cli.js:89:27
    at Object.<anonymous> (/home/jsamr/tmp/api-docs-gen/lib/cli.js:92:7)
    at Module._compile (internal/modules/cjs/loader.js:1251:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1272:10)

To reproduce, apply this patch on master (16585f9):

diff --git a/examples/packages/utilities/src/index.ts b/examples/packages/utilities/src/index.ts
index 64a02e2..6507747 100644
--- a/examples/packages/utilities/src/index.ts
+++ b/examples/packages/utilities/src/index.ts
@@ -70,3 +70,17 @@ export function isSymbol(val: unknown): val is symbol {
 export function isPromise<T = any>(val: unknown): val is Promise<T> { // eslint-disable-line
   return isObject(val) && isFunction(val.then) && isFunction(val.catch)
 }
+
+/**
+ * A
+ *
+ * @public
+ */
+export type A = string;
+
+/**
+ * {@link A}
+ *
+ * @public
+ */
+export type B = number;

I have investigated a little. Resolver is sometimes undefined, so here is a hotfix:

diff --git a/src/processor/utils.ts b/src/processor/utils.ts
index bbc8667..e12d296 100644
--- a/src/processor/utils.ts
+++ b/src/processor/utils.ts
@@ -764,7 +764,7 @@ export function getDocSectionContent(
               codeDestination,
               contextItem
             )
-            if (result.resolvedApiItem) {
+            if (result.resolvedApiItem && resolver) {
               const filepath = resolver(
                 style,
                 result.resolvedApiItem,

What is your plan for this project?

@kazupon Let's be honest, this project is a very promising alternative to the somehow limited api-documenter! I just want to know if it is worth the time investment. What I mean by that is that I'd love to use it in my open-source projects, and I'd be happy, beyond the reports I have already submitted, to test and send feedbacks on a regular basis. My question is, is it a hobby / prototype or do you have a reasonable confidence that it will receive frequent maintenance and dedication?

basic generator

  • functions
  • enumrations
  • variables
  • type alias
  • class
  • interface

Invalid markdown generated from function signatures having parameters typed with parametrized types

Example:

/**
 * A dumb type
 */
export type DumbType<T> = { foo: T };

/**
 *
 * @param dummy - A dummy
 */
export function undumbify<T>(dummy: DumbType<T>): T { return dummy.foo };

Will produce:

### undumbify

...

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| dummy | DumbType<T> | A dummy |

The less-than and greater-than signs should be escaped. Otherwise, it is considered an opening HTML tag.
To reproduce, apply this patch on master (16585f9):

diff --git a/examples/packages/utilities/src/index.ts b/examples/packages/utilities/src/index.ts
index 64a02e2..4ccb387 100644
--- a/examples/packages/utilities/src/index.ts
+++ b/examples/packages/utilities/src/index.ts
@@ -70,3 +70,14 @@ export function isSymbol(val: unknown): val is symbol {
 export function isPromise<T = any>(val: unknown): val is Promise<T> { // eslint-disable-line
   return isObject(val) && isFunction(val.then) && isFunction(val.catch)
 }
+
+/**
+ * A dumb type
+ */
+export type DumbType<T> = { foo: T };
+
+/**
+ *
+ * @param dummy - A dummy
+ */
+export function undumbify<T>(dummy: DumbType<T>): T { return dummy.foo };

And run

yarn example:setup
yarn example:build
yarn example:extract
yarn example:gen
yarn example:docs

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.