Use jsdoc (or another tool?) to document .vue files

[kinow]

Describe exactly what you would like to see in an upcoming release

At the moment jsdoc is parsing our .js files, but not the .vue files. I noticed this when I was writing some docs some days ago for @giulianoserrao . I wanted to update our Wiki here with auto-generated docs, instead of writing manually about each component.

I thought since we had jsdoc it would be just a copy and paste job until we had some GH action updating gh-pages or the Wiki, but alas it's not working as expected.

Additional context

Pull requests welcome!

[kinow]

• 👎 jsdoc-vuejs
  • was the first search hit I found; it's not part of the vue org, and while it has ~9 contributors, not sure whether it'd be compatible with Vue3 and going forward. Tested and installed it, but without success trying to run it to generate docs for our existing components.
• 🤔 vuepress
  • part of the Vue org; I think Vue uses Vuepress for its website documentation too; generates docs sites that look standardized like ReadTheDocs?
  • Good reference: https://www.xiegerts.com/post/creating-vue-component-library-documentation/
• 👎 propdocs
  • repo is archived
• 👎 Storybook
  • looks interesting, but also way more powerful than what we need; also appears to require creating files with the docs for each component, so I guess docs & code could get out-of-sync?
• 👎 jsdoc
  • I think, in theory, that there should be some way to tell jsdoc to use the webpack+babel generated files (i.e. the js files generated after the .vue components are processed), but after looking at existing ways of doing that, I couldn't find anyone doing it, and implementing from scratch doesn't sound simple (nor easy for myself or others to maintain IMO) — it would make sense to keep it simple and use jsdoc; I tried it before jsdoc-vuejs (above)

[kinow]

95% done with Vuepress for now. Looking good IMO, but some of what I'm doing probably overlaps with the UI guide I think (the one we have within Cylc UI, accessible to users). Maybe they should converge somehow?