route4me/route4me-nodejs-sdk

DOC toolchain

Closed this issue · 1 comments

maxkoryukov commented

Ancestor of #17

maxkoryukov commented

As we previously discussed with Oleg : gitbook is a very good tool for documentation.

Pros:

  • consume GFM (github flavored markdown)
  • have pretty themes (including dark and custom) out of the box, switching on the fly
  • allow to export PDF book (and several other book format)
  • supports online editing with clever online editor
  • sync with github
  • external-hosting (need to ensure, that external site looks like gitbook-hosted for end-user)
  • Multilingual support!
  • easy extendable:
    • themes
    • plugins 🛠️

Cons:

  • again : markdown. Not every autodoc tool supports for markdown output (for example, jsdoc can't create documentation in md format out of the box. Additional tools required)
  • tool-belt will include another one tool..
  • ???

Folder structure

gitbook structure depends on:

  1. SUMMARY.md - Table of Contents
  2. folder structure

So, you are free to use any layout for files, BUT you must maintain structure in SUMMARY.md

It is a cons and pros at the same time.

I hope, there is a plugin for autogenerating SUMMARY.md