search

aframevr / aframe

:a: Web framework for building virtual reality experiences.
https://aframe.io/
MIT License
16.63k stars 3.95k forks source link

Automatically generate Markdown docs #710

Closed ngokevin closed 8 years ago

ngokevin commented 8 years ago

Issue by cvan Friday Dec 04, 2015 at 03:41 GMT Originally opened as https://github.com/aframevr/aframe-core/issues/594

The A-Frame site uses Markdown (.md) docs and renders them to HTML in the build step. We will be slurping up aframe-core's .md docs from this repo's docs/ directory (and same goes for the aframe repo's).

I was able to get JS Doc doc comments generated to Markdown using jsdoc2md:

https://gist.github.com/cvan/f50ae50fd4cfb2101b9c#file-all-md

Research

https://github.com/jsdoc2md/jsdoc-to-markdown – not great, but the most promising https://github.com/tj/dox – decent output, but returns JSON not Markdown https://github.com/tjchaplin/mox – no https://github.com/cbou/markdox – no https://github.com/sutoiku/jsdox – no http://jashkenas.github.io/docco/ – nouseful for only inline docs, not API reference docs https://github.com/jamesramsay/hercule#advanced-use-default-placeholders – meh, but interesting https://github.com/jsdoc3/jsdoc – nope, doesn't properly support Markdown (lots of bugs, tables don't work, and a bunch of other useful Markdown syntax)

Relevant examples of JS Doc for modules

http://usejsdoc.org/howto-commonjs-modules.html https://github.com/olivernn/lunr.js/blob/master/lunr.js

ngokevin commented 8 years ago

Comment by cvan Saturday Dec 05, 2015 at 11:18 GMT

There's also https://github.com/documentationjs

cvan commented 8 years ago

Not sure we need this or should do this anytime soon.

ngokevin commented 8 years ago

don't think we need this