Add automated API docs #27

New issue

Open

opened 2024-06-19 21:05:12 +00:00 by jsheunis · 5 comments

jsheunis commented

2024-06-19 21:05:12 +00:00

(Migrated from github.com)

Look into JSdoc; https://github.com/psychoinformatics-de/shacl-vue/pull/26/commits/863e84c825cf1ff8c858c9255b382ebfa6f2879e already has a single example of a jsdoc-based docstring for a module.

For an html theme, investigate:

Look into JSdoc; https://github.com/psychoinformatics-de/shacl-vue/pull/26/commits/863e84c825cf1ff8c858c9255b382ebfa6f2879e already has a single example of a jsdoc-based docstring for a module. For an html theme, investigate: - https://github.com/ankitskvmdam/clean-jsdoc-theme - https://github.com/SoftwareBrothers/better-docs - https://github.com/clenemt/docdash

jsheunis commented

2024-09-05 11:30:53 +00:00

(Migrated from github.com)

JSDoc can be used for api documentation.

For general user and developer documentation, I have decided to go with Vitepress, since it's compatible with vuejs 3 and powered by vite tooling which is already used for the build process of this package.

JSDoc can be used for api documentation. For general user and developer documentation, I have decided to go with [Vitepress](https://vitepress.dev/), since it's compatible with vuejs 3 and powered by vite tooling which is already used for the build process of this package.

jsheunis commented

2024-09-05 13:42:48 +00:00

(Migrated from github.com)

With f432d21b86 to df848e252c we now have a setup for docs that are deployed together with the demo shacl-vue application (at /docs) via github pages.

With f432d21b86ff2240c07798f5d54942239ae80822 to df848e252ce9b1a944b7fa46fec6ffcae3d57a47 we now have a setup for docs that are deployed together with the demo shacl-vue application (at `/docs`) via github pages.

jsheunis commented

2024-09-09 07:36:36 +00:00

(Migrated from github.com)

The only step left to figure out is how to use jdoc for api doc generation and then make the resulting pages part of the docs generated by vitepress

Could aim to get a script that runs through vue components, generates markdown from their jsdoc-style comments and docstrings, and then adds those markdown files to the sources for vitepress to build the docs site from.

Look into:

The only step left to figure out is how to use jdoc for api doc generation and then make the resulting pages part of the docs generated by vitepress Could aim to get a script that runs through vue components, generates markdown from their jsdoc-style comments and docstrings, and then adds those markdown files to the sources for vitepress to build the docs site from. Look into: - https://github.com/vue-styleguidist/vue-styleguidist - https://github.com/antfu/vite-plugin-md

jsheunis commented

2025-03-18 11:04:20 +00:00

(Migrated from github.com)

Most recently maintained theme for jsdoc that I could find is https://github.com/ankitskvmdam/clean-jsdoc-theme. The default jsdoc theme looks really bad.

jsheunis commented

2025-05-19 08:27:26 +00:00

(Migrated from github.com)

Docs are currently built on PR/merge and deployed to github pages. The missing piece remains autogenerating Javascript API docs from docstrings. Also, with the refactoring and separation of shacl-tulip, the idea is to include its docs (mainly API) into a subsection of shacl-vue

Docs are currently built on PR/merge and deployed to github pages. The missing piece remains autogenerating Javascript API docs from docstrings. Also, with the refactoring and separation of `shacl-tulip`, the idea is to include its docs (mainly API) into a subsection of `shacl-vue`