Working on viz docs

This repository's docs are set up like all of Tidepool's front-end and docs repos. For details on this setup, see the general guidance for docs setup & workflow.

Setup

To summarize briefly, the steps you will need to have done in order to use the npm scripts configured for docs work in the repository are:

• clone a second copy of this repository as a subdirectory web/; you can do this from your viz/ directory with git clone git@github.com:tidepool-org/viz.git web
• switch to the gh-pages branch in the embedded clone and delete the master branch

$ cd web/
$ git checkout gh-pages
$ git branch -d master

Regenerating

We generate Markdown documentation for the utilities in src/utils/ from the JSDoc comments included with all exports and/or functions. The README in src/utils/ documents how to regenerate these Markdown files; this regeneration should be performed whenever you've added or updated a utility functon and/or the JSDoc for that utility.

Publishing

To publish revised docs and/or Storybooks, run the following from the root of the viz/ directory:

For updating just docs (including the adidocs/ in src/utils/) by building the static GitBook site that we publish to GitHub Pages:

$ npm run build-docs

Then cd web/ and review the unstaged changes. Stage & commit the changes you want to make. Finally, "publish" to GitHub pages by pushing to the upstream gh-pages branch.

For updating the Storybooks (again from the root of viz/:

$ npm run build-storybooks

Again navigate into the embedded web/ directory to review, stage, commit, and push the changes upstream.