search

nwfsc-fram / boatnet

At-Sea Field Data Collection Software Components for Scientific Surveys and Observers
8 stars 5 forks source link

Boatnet Component Documentation - define how #829

Closed ghost closed 4 years ago

ghost commented 5 years ago

Please see #828 for how we will do this.

SaOgaz-NOAA commented 5 years ago

So far I've seen two viable options for this, and a third that I'm not crazy about and is deprecated anyway. Here are my notes so far:

Less good option:

SaOgaz-NOAA commented 5 years ago

Goal to have samples of both of these to show the team Monday Oct 7th.

ghost commented 5 years ago

reference: https://github.com/vuejs/awesome-vue#docs

ghost commented 5 years ago

Vue Press as a possibility:

https://www.smashingmagazine.com/2019/08/vuepress-documentation/

@SaOgaz-NOAA @melinashak-noaa @wsmith-nwfsc @sethgerou-noaa

SaOgaz-NOAA commented 5 years ago

Tried to test several different packages today, ran into various problems.

Vue Press - Could not get this guy to work with boatnet, might be worth a few more tries through

Vuese - it "worked", but it didn't like the way we were writing our vue boatnet components, so it wasn't pulling out most of the docstrings.

Vue Styleguidist - Depedency hell with this one. I think there's some kind of conflict with webpack and core-js and styleguidist... I would like to maybe grab someone else to look at this with me, might make more progress with two heads instead of one.

SaOgaz-NOAA commented 4 years ago

More upates:

Vue-Styleguidist Will and I looked more into vue-styleguidist but could not get it to work in boatnet (even with the simple example app). It had a problem with not being able to find a vue file. Additionally it requires an older version of webpack.. which may or may not be the source of the problem, but even if it's not, not the best depedency to have.

vuese Got this to work really easily on the second attempt out of the box! The caveat to this is, it only liked the formatting/syntax of two of our boatnet apps... example, and obs-wcgop-optecs. That being said, the generated docs looks really simple and clean, but I think in a good way. It might not be too much work to massage the other apps to have a syntax vuese will accept.

Vuepress This library is really nice, and has a ton of features. Unfortunately it doesn't auto-generate docs from existing app components. It can have it's own doc components, which are then usable in the live documentation. Here's a link to someone who rolled their own to hook some component auto-doc stuff into vuepress: https://medium.com/@ismayilkhayredinov/vue-component-docs-with-vuepress-and-vuedoc-parser-7855c61562e8.

My conclusion: Vuepress is nice, and might be a really good option for our outside user documentation (not sure what the status/plans are for that...), but not such a good choice for our internal component documentation. I would definitely recommend vuese for that. It's light-weight, gave me no installation problems, worked out of the box on some of boatnet, and looks pretty good with no extra styling. Follow up question would be, can you do any additional styling etc. in vuese?

SaOgaz-NOAA commented 4 years ago

Extra notes on other docs from the list in the link:

vuedoc/md - doesn't say anything about typescript...

https://gitlab.com/vuedoc/md

jsdoc-vue-component - ?

Vuedoc Parser - generates JSON, so not really a user doc on it's own

vue-Elucidate (NOT under active dev, doesn't support typescript):

https://github.com/mattrothenberg/vue-elucidate, uses written in props

vue-styleguide-generator (deprecated)

propdoc (DEPRECATED on github): https://alligator.io/vuejs/propdoc-document-components/

documents not generated from comment strings but instead from added 
properties in the components. Not crazy about this, someone not familiar
with propdoc could be very confused...
i.e.
SaOgaz-NOAA commented 4 years ago

Issues with vuese on the other boatnet components resolved, it now works nicely with all our components when the right doc strings are added. There's one small exception with the automatic parsing some of the Vue class decorators, but I think we can use a work around for that case.

SaOgaz-NOAA commented 4 years ago

Vuese would not work with the composition-api style. However, I couldn't find any information on any libraries that do support this, so I suspect we'd be in that situation no matter what.

SaOgaz-NOAA commented 4 years ago

Going with full test run of vuese, opening new issue.