GitBook documentation (proposal)

Proposal to use GitBook to build the documentation and serve it through the GitHub pages of the Chart.js GitHub project.

Example: deferred/docs

Main issues with the current doc

  • not (yet) part of the continous integration process, no access to the sources
  • need to tweak external (not accessible) scripts to add new pages
  • can't add multiple charts on the same page?!
  • "one page" format not optimal for substantial documentation
  • no mobile friendly responsive implementation
  • can't have doc versioning (doc.chartjs.org/2.4.0/*)
  • can't have dev preview (doc.chartjs.org/dev/*)

GitBook as doc generator

  • same format (markdown), same look-and-feel, same location (Chart.js repo)
  • many plugins, provides everything we need
  • Chart.js plugin to embed our charts in the doc
  • better navigation (per page), works better with large content
  • responsive with a mobile friendly version
  • can add charts directly in the markdown files
  • can have multiple charts per page
  • can easily include new page or reorganize the TOC
  • can include jsFiddle or CodePen examples
  • NPM CLI, can be generated from Gulp

Simply requires to add a book.json and SUMMARY.md to the Chart.js repo and NPM gitbook-cli dependency.

Continous integration

  • for new tag: Travis builds and deploys the doc to GH pages (docs/{tag}/*)
  • for new tag: Travis re-generates the docs/latest/index.html redirection page
  • for commit in master: Travis builds and deploys the doc to (docs/dev/*)

Requires to redirect www.chartjs.org/docs/ to docs.chartjs.org and have docs.chartjs.org to point on chartjs.github.io/Chart.js/docs (see this guide).

Other examples

results matching ""

    No results matching ""