Explore auto-generating documentation for composables

[MisRob]

❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.

Summary

When the documentation website is built, there's logic that automatically extracts JSDoc comments from a KDS component and then inserts them into the component's documentation page.

For example, in the KImg component, the scaleType prop is documented with:

https://github.com/learningequality/kolibri-design-system/blob/0cbdf57d24690cb6c23618ba700118a831cd9ffc/lib/KImg/index.vue#L124-L132

When the website is built, the comment is automatically inserted into the "Props" section at the bottom of the KImg documentation page:

The same applies to components' "Events" and "Slots".

However, this only works for components, not for composables. For example, let’s have a look at useKShow composable. Even though useKShow's documentation page contains “Parameters” and “Returns”

These are not auto-generated from JSDoc, but written manually here

https://github.com/learningequality/kolibri-design-system/blob/0cbdf57d24690cb6c23618ba700118a831cd9ffc/docs/pages/usekshow.vue#L109-L117

As we're moving toward using composables more widely in our products and Design System will soon have some new ones, it'd be valuable to have this bottom part of the documentation auto-generated for composables as well.

The goal of this issue is to research if and how we could achieve this and eventually prepare a proof of concept (PoC) implementation. Part of this issue is also exploring how the documentation website should roughly look like if a composable has more publicly exposed entities, such as more functions, some refs, some computed, etc.

Guidance

• See “Updating the library components documentation”, utils/extractApi.js, and DocsPageTemplate.vue to understand the current auto-generation system
• In the first iteration, it would be fine for the PoC to only generate “Parameters” and “Returns” sections right from the JSDoc comments here https://github.com/learningequality/kolibri-design-system/blob/0cbdf57d24690cb6c23618ba700118a831cd9ffc/lib/composables/useKShow/index.js#L26-L52
• However, the approach taken to prepare the PoC needs to be scalable since composables can contain much more than just one function - there could be more functions, computed, watchers, etc. Even though it would be nice, we definitely don’t need to support docs auto-generation for all possibilities. Nevertheless, we should be certain we will be able to add support gradually as the need arises without much trouble.
• Relatedly, it could be suitable to use an existing library for extracting JSDoc, if there's one (similarly to how vue-docgen-api is currently utilized for components)

The Value Add

Efficiency in creating new and maintaining existing documentation.

Possible Tradeoffs

Potential complexity of the task in light of currently having just few composables (as of July 2024). That’s one of the reasons this issue is scoped rather as exploration at this point.

Comments

If it seems that this idea is not feasible, in the scope of this issue we could at least consider how to make writing of the API section of the composable documentation more efficient, for example in the form of some new documentation utilities or components.

[lokesh-sagi125]

hey @MisRob, can you assign me to this issue? I would like to work on the research part along with other issues if this issue is not time-sensitive. thank you

[MisRob]

Yes @lokesh-sagi125. It's not time sensitive at all, so feel free to play around :) See you again later in January!

[MisRob]

Thank you

[lokesh-sagi125]

thank you @MisRob , yes see you in jan :)

[MisRob]

Hi @lokesh-sagi125, I wanted to mention that Learning Equality will be closed from December 23 to January 5.

[AlexVelezLl]

Hi @lokesh-sagi125! Are you still working on this issue? No rush, just checking-in in case it would be better to reassign :).

[lokesh-sagi125]

Hey @AlexVelezLl, I did some research on this issue, but currently am working on other issues assigned to me. You can reassign since it would open up new issues for the new contributors :).

[AlexVelezLl]

Thanks @lokesh-sagi125! I will unassign you then 🤗, If you want to pick this up later and its still unassigned, feel free to ask to be reassigned!

[GautamBytes]

Hello @AlexVelezLl , you can assign me this issue as my other 2 out of 3 issues are done and would need minor tweaks when reviewed , till then i can research and see how can i contribute to this issue. Thanks!

[SukhvirKooner]

Hi @MisRob , I’d like to propose a solution for auto-generating documentation for composables. Based on the guidance, I’ll:

1. Research the current system (utils/extractApi.js, DocsPageTemplate.vue) to understand component documentation generation.
2. Build a PoC focusing on "Parameters" and "Returns" sections from JSDoc comments for composables.
3. Ensure scalability to support additional entities (functions, refs, etc.) and explore existing libraries like vue-docgen-api.
4. Propose a documentation layout for complex composables.

This approach aligns with the issue goals and ensures future extensibility. Please assign this to me so I can start on the PoC.

[MisRob]

Hi @SukhvirKooner, this is what the issue description states, yes. However, I will go ahead and assign @GautamBytes who was here sooner.

@GautamBytes thank you and let me assign you. However I'd like to bring to your attention what I mentioned previously:

However note this would be really about research and proof of concept - if we find out it's not feasible, we may decide to not move in this direction. Still, I see value in it and would appreciate if someone looked at it quite independently. Depending on your goals, you should know it may not be the most rewarding task :)

You're welcome to think about it and then let us know what works for you.

---

P.S. Perhaps you two can connect and collaborate if that'd be interesting since this task could probably use more eyes!Up to you ;)

[learning-equality-bot[bot]]

Automatically unassigning @GautamBytes due to no comments here, or updates on the associated pull request for 1 month. @GautamBytes, if you're still interested in this issue or already have work in progress, please message us here, and we'll assign you again. Thank you!