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

Spike: replace strong-docs with api-extractor #2507

Closed
3 of 4 tasks
bajtos opened this issue Feb 28, 2019 · 4 comments
Closed
3 of 4 tasks

Spike: replace strong-docs with api-extractor #2507

bajtos opened this issue Feb 28, 2019 · 4 comments
Assignees
Labels
Internal Tooling Issues related to our tooling and monorepo infrastructore spike

Comments

@bajtos
Copy link
Member

bajtos commented Feb 28, 2019

Can we replace our home-grown apidocs solution based on strong-docs with https://api-extractor.com?

API Extractor offers additional benefits beyond API docs generation, e.g. support for Alpha/Beta graduation and ability to remove internal classes/members from the generated .d.ts files.

Acceptance criteria

  • Use api-extractor to parse TypeScript sources and produce JSON files describing the API
  • Convert *.api.json files into format we can consume by http://apidocs.loopback.io. We should research different alternatives, for example using api-documenter to build Markdown files or writing our own converter that can produce HTML files.
  • Propose the new apidocs pipeline: what steps to run at publish time, what artifacts to bundle in the npm packages, what steps will be run by our apidocs site.
  • List of user stories/tasks needed to switch loopback-next from strong-docs to api-extractor.

Related PRs: #2834 and #3055

@bajtos bajtos added spike 2019Q2 Internal Tooling Issues related to our tooling and monorepo infrastructore labels Feb 28, 2019
@hacksparrow
Copy link
Contributor

Good suggestion. We should go for it.

@jannyHou
Copy link
Contributor

jannyHou commented Mar 4, 2019

I like its API review features like catching the API contracts change and checking the type export. Let's try it +1.

In case we want to try an alternative: I found a similar API generator tool typedoc, given a rough comparison typedoc has plugins for setting up pipelines and rendering markdown API documents.

@dhmlau
Copy link
Member

dhmlau commented May 7, 2019

assign it to @raymondfeng , since he has a PR #2834 for this.

@dhmlau
Copy link
Member

dhmlau commented Jun 11, 2019

Talked to @raymondfeng, we can close this as done.

@dhmlau dhmlau closed this as completed Jun 11, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Internal Tooling Issues related to our tooling and monorepo infrastructore spike
Projects
None yet
Development

No branches or pull requests

5 participants