-
Notifications
You must be signed in to change notification settings - Fork 20
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
[Feature] Combine guides with API content #24
Comments
Well, I've had some experience with what you're suggesting. Before I created this library, I had another private version of it in which this feature was available, i.e. it was possible to render the API directly in the guides, I thought just like you that it could be convenient for users, but after collecting the metric, it became clear that users, first of all, look at the demo and various examples and they look at the API of components only as a last resort when they have not found a suitable example or if there are problems with it, in other cases, they are not very interested in it. Moreover, some guides may contain examples of using combinations of components, for example, the Please understand me correctly, this is a relatively simple feature and it can easily be done. I just don't want to create controversial solutions. I mean that API pages will be improved over time to give users more information, structure it, and show all the necessary connections between entities. Displaying the same thing in the guide would be excessive, and displaying only part of the API sounds questionable and strange. I liked the approach of MUI, which I would like to suggest you consider. They also write guides showing the various possibilities of their component library and at the end of such guides, they provide links to API pages. Meanwhile, I wouldn't close this ticket and see what other users might say in the future. |
Yes, I see your point. My dilemma is that I don't know whether to put the content in the guides or the jsdoc comments. As you point out, users will look at the guide first so I want the guide to have a good description of the component and its inputs/outputs, but I would prefer for that content to live in the jsdoc so that it is also accessible within the IDE and for other devs on my project who are reading the source code. For now I will just put up with a bit of duplication and add links in both directions. |
Yes, I understand that documentation for a component library is the most ambiguous because almost every element of the library requires visual examples, but at the same time, it would be desirable to document them in the code using comments. In this case, I think that the documentation should be strictly divided into two types:
|
@semicolin Hey, I decided to revisit this ticket, and I think I have a new idea on how it could be implemented: I could add a new type of guide, which is a combination of an API and export interface NgDocApiPage extends NgDocPage {
/**
* Any declaration that should be used to show the API.
*/
declaration: any;
} Here, you can see that the interface inherits from In the end, NgDoc could generate and display a similar header as it does on the API page, with selectors for the declaration name automatically. The content you write in It's important to note that if this type of guide is used, the specified declaration will NOT be displayed in the API List. Otherwise, it would cause conflicts with keywords. What do you think about this? |
That's an interesting idea, but removing the declaration from the API List is not ideal. Could the API List link to the API Guide? |
I think yes that's possible!
Initially, I was thinking about importing and assigning a class, for example: import { MyClass } from 'my-lib';
export const page = {
declaration: MyClass
}
export default page; But there might be situations where someone wants to create a similar page for an interface or another type of declaration that doesn't exist at runtime. However, in theory, I could try combining these two options. |
I wanted to chime in here.🛎️ I came here looking for this feature. 👀 I'm writing tutorial-like documentation, and I generally start with the API description and then dive into the usage. The API documentation is written in jsdoc already. It seems redundant to repeat it 🔁, yet sending people off to API land to read it seems like a poor user experience For now, I will have to choose redundancy over poor user experience. BTW, I love what you have here. Once it is set up, it is pretty easy to use.🚀 |
@DaveMBush Thank you! But yeah totally agree, I'm gonna start working on this after SSR support |
I've been refactoring the core part of the engine for quite some time, and finally, I've started implementing this feature. I've come up with a new idea that seems more flexible to me, and it departs from the initial proposal:
const MyPage: NgDocPage = {
title: `My Page`,
mdFile: ['./index.md', './api.md'],
}; In this case, each markdown file will be considered a separate page, displayed as individual tabs.
api.md
---
title: API
icon: button-icon
route: api
---
api.md
---
title: API
icon: button-icon
route: api
---
{{ NgDocActions.api('libs/ui-kit/components/button.ts#ButtonComponent') }} index.md
# ButtonComponent
## API
{{ NgDocActions.api('libs/ui-kit/components/button.ts#ButtonComponent') }} |
Description
When I write a guide for one of my library's components, I want to include API documentation for that component's class (inputs, outputs, properties, methods, jsdoc comments) alongside the guide's markdown and demos so readers can find all relevant documentation for a component in one place (like the Angular Material docs for example). Currently, API and Guide are separate pages and I don't see any way to combine them, aside from adding a link to the corresponding API page.
Proposed solution
Maybe add methods to NgDocActions for rendering the API documentation (or pieces of the API documentation)? For example:
Maybe this could be accomplished with existing functionality by doing something like
but I haven't figured out how to wire that up, if it's even possible.
Alternatives considered
If you are planning to do #21 maybe you could add a Guide tab on the API page that pulls its content from a page with corresponding
NgDocPage.api
property (or something like that). Then render that API page (including Guide tab) in place of the guide page.The text was updated successfully, but these errors were encountered: