ng-doc
[Feature] Generate / Export documented lib API only
Description
Hello,
I would like to request a way to use some part of the documentation builder in a standalone way. I am working on a component library, and we have a homemade documentation app that is quite heavily customized and specific.
To document component's api, we currently use Compodoc to generate a json file with all information about our public api (components, classes, inputs, outputs, their types, etc). It also allows us to check if we do not make breaking changes in the API between versions.
Compodoc is not without its fair share of issues, especially since recent Angular novelties with signal inputs, for example. Your project seem more modern and robust on this topic and I would really like to be able to try its "api extractor" directly, instead of Compodoc, given that switching to a full ng-doc setup is not possible on our side.
Maybe it is already possible in some way, but i didn't manage to find it in the doc if it is :(
Proposed solution
A TS API (not necessarily a CLI), to get the "raw" form of the content used in api references pages, available separately from the builder.
Alternatives considered
Already using Compodoc, but it is quite heavy and has a lot of issues.
Hey, sorry for the delay, could you clarify in what format you are interested in generating API documentation? NgDoc renders documentation in HTML, which is then added to pages. In general, you might be able to use Nunjucks on your side and leverage some of the functions contained in the builder library, similar to how NgDoc does it, to allow for full customization. However, I need to know more details to assist you with this.
A way to get a json object containing every public api information would be great (inputs, outputs, components, public methods, default values, jsdoc comments and tags, etc). Given that we already have an app and dedicated screens, I guess Nunjucks would be redundant, because that would be like rendering a json object as... a "page" being in fact a json object, that we would then consume. Like you said, I would probably be interested in leveraging some stuff coming from your builder library but I may lack the time to try to find it myself, and I would not like to rely on internal stuff anyway.
I see, unfortunately, NgDoc does not generate an API in JSON format instead, it renders all the information directly in Nunjucks templates using pure functions. The thing is, I considered it unnecessary to generate JSON and then re-render it into HTML when functions can be called directly from the Nunjucks template.
In general, you could use the those pure functions directly, and I could assist you with that. Their only dependencies are the ts-morph library, which helps gather information about declarations, and tsdoc, which is used in some places for extracting comments. You can take a look at how the class template is rendered here; overall, there’s nothing too complex there, and I think it could easily be used for creating JSON. All the pure functions can be found here.
However, I will consider moving this generation to a separate library with JSON formatting. It could simplify my template code and, overall, make the code cleaner.
What is the outcome of your considerations?
@skoropadas
Background is, the more compodoc is looking to not be a feasible tool for modern angular docs, storybook's reliance on this is becoming more and more of an issue.
Since there are some discussions about a future exchange of compodoc and your project and approach is some of the most robust and modern implementations, is there any way you could leverage your talent and expertise to create or expose a usable, lightweight replacement/API where some tools of ng doc could be used by storybook to generate the info that's needed?
It's mostly json, so the feature request above. Or like react-docgen-typescript is used, there is no generated json.
Is there any way you would see an integration, API, plugin/add-on or a even a collaboration or deeper discussion with the storybook folks about what's possible in your roadmap? Or just draft what would be needed to leverage the existing ng-doc functionalities to build into storybook? This would give good exposure to your nice project here, cause e.g. for our use case, a secondary documentation like the compodoc html is needed besides storybook, and it would be so nice to be able to have the same tools under the hood for customization.
I appreciate the work you did here!
