search

transitive-bullshit / update-markdown-jsdoc

Updates a markdown document section with jsdoc documentation.
8 stars 1 forks source link

hope can support typescript #5

Open bluelovers opened 6 years ago

bluelovers commented 6 years ago

this moudle output style is best, and easy use but if can support typescript is more better

berstend commented 5 years ago

@bluelovers I'm in the same boat as I'm more and more migrating to TypeScript.

The best option right now seems to be typedoc-plugin-markdown, which ends up looking like this.

Still not as pretty as the output update-markdown-jsdoc unfortunately (too verbose and not confined to a single .md page, other typedoc issues regarding inheritance).

Given the lack of options I'm quite motivated to work on a spiritual sibling of this project for typescript. 😄

berstend commented 4 years ago

@bluelovers it's finally possible with documentation.js 😄 

npx documentation readme --quiet --shallow --github --readme-file README.md --section API ./src/index.ts

I'm now trying to extract/backport the changes transitive-bullshit made in documentation-custom-markdown to a documentation theme or plugin. :)

edit, changes we need to port are on the right: https://www.diffchecker.com/URXY9FrS

edit2, argh:

The default Markdown generator for documentation.js isn't customizable - instead of a plain-text theme, it's generated by creating an AST and then rendering it with remark. If you need something extra in Markdown, you can either rally for that thing to be included in the default theme, or you can hack around it by using an HTML theme that outputs Markdown.

berstend commented 4 years ago

So I ended up with a fork as well 😅

I tried to implement these changes by adding "generic" markdown theme support (--markdown-theme), so I can lobby for this to be added in documentation.js eventually.

The fork and documentation can be found here: https://github.com/berstend/documentation-markdown-themes/wiki#documentationjs-with-markdown-theme-support

I built on top of transitive-bullshit's modifications and added some ideas from the puppeteer doc style as well.

transitivebs is the only markdown theme supported right now:

yarn documentation readme --quiet --shallow --github --markdown-theme transitivebs --readme-file README.md --section API src/index.ts

Example output:

Very similar to the nice design that update-markdown-jsdoc outputs, with some additional ideas. Quite happy with it and due to the new documentation version it now supports TypeScript as well. :)

transitive-bullshit commented 4 years ago

Really like this @berstend -- great work!

I'd be happy to add this to update-markdown-jsdoc. Let me know if you'd like to be added as a collaborator so you can make any changes without me getting in the way 😄