Local development script

[leoj3n]

setup.zsh:

#!/usr/bin/env zsh

set -x

#
# this script:
#   - git clones bit-docs-website to ./web/bit-docs-website
#   - makes a ./tbd directory to hold packages that are "to be documented"
#   - git clones the repos specified in `packages` array (below) to ./tbd
#   - symlinks the local repos "to be documented" into bit-docs-website
#   - runs npm install inside each cloned repo directory
#   - runs the command to generate the website in bit-docs-website
#   - starts a web server to serve the generated ./web/bit-docs-website/gh-pages
#

thisdir="${0:A:h}"
tbd="${thisdir}/tbd"
web="${thisdir}/web"
website="${web}/bit-docs-website"
packages=('bit-docs' 'bit-docs-generate-html' 'bit-docs-process-tags' 'bit-docs-glob-finder' 'bit-docs-generate-readme')

#
# get local copy of bit-docs-website (will skip/fail if already exists)
#

mkdir "${web}" && git clone "https://github.com/bit-docs/bit-docs-website.git" "${website}"
npm update --prefix "${website}" && npm run bit-docs --prefix "${website}"

#
# clone repos locally (will skip/fail if already exists)
#

mkdir "${tbd}"

for repo in "${packages[@]}"
do
  git clone "https://github.com/bit-docs/${repo}.git" "${tbd}/${repo}" && npm install --prefix "${tbd}/${repo}"
done

#
# replace packages installed by npm with local repos
#

for dir in "${packages[@]}"
do
  rm -rf "${website}/node_modules/${dir}"
  ln -s "${tbd}/${dir}" "${website}/node_modules/"

  if ! [[ "${dir}" == 'bit-docs' ]]; then
    rm -rf "${website}/node_modules/bit-docs/lib/configure/node_modules/${dir}"
    ln -s "${tbd}/${dir}" "${website}/node_modules/bit-docs/lib/configure/node_modules/"
  fi
done

#
# make sure the bit-docs bin is linked
#

ln -sF '../bit-docs/bin/bit-docs' "${website}/node_modules/.bin/bit-docs"

#
# regenerate website documentation with new local repos
#

npm run bit-docs --prefix "${website}"

#
# start webserver hosting generated site
#

npm install -g http-server && http-server "${website}/gh-pages"

This script will result in a directory structure like:

.
├── setup.zsh
├── tbd
│   ├── bit-docs
│   ├── bit-docs-generate-html
│   ├── bit-docs-glob-finder
│   └── bit-docs-process-tags
└── web
    └── bit-docs-website

As you add packages into ./web/bit-docs-website/package.json like:

  "devDependencies": {
    ...
    "bit-docs-generate-readme": "^0.0.10"
  },
  "bit-docs": {
    ...
    "glob": {
      "pattern": "{node_modules,docs}/{bit-docs,bit-docs-generate-readme}/**/*.{js,md}",
      ...
    },
    ...
  }

Also add the new package into the setup script's packages array like:

packages=('bit-docs' ... 'bit-docs-generate-readme')

Then, you can re-run the script, and the new package repo will be injected to ./web/bit-docs-website and ready for local development at, for example, ./tbd/bit-docs-generate-readme.

[leoj3n]

Updated script allows granularity between documented devDeps and used plugins:

#!/usr/bin/env zsh

set -x

#
# this script:
#   - git clones bit-docs-website to ./web/bit-docs-website
#   - makes a ./tbd directory to hold devDeps that are "to be documented"
#   - git clones the repos specified in `devDeps` array (below) to ./tbd
#   - symlinks the local repos "to be documented" into bit-docs-website
#   - runs npm install inside each cloned repo directory
#   - runs the command to generate the website in bit-docs-website
#   - starts a web server to serve the generated ./web/bit-docs-website/gh-pages
#

thisdir="${0:A:h}"
tbd="${thisdir}/tbd"
web="${thisdir}/web"
website="${web}/bit-docs-website"
node_modules="${website}/node_modules/bit-docs/lib/configure/node_modules"
devDeps=(
  'bit-docs'
  'bit-docs-dev'
  'bit-docs-generate-html'
  'bit-docs-generate-readme'
  'bit-docs-glob-finder'
  'bit-docs-js'
  'bit-docs-process-mustache'
  'bit-docs-process-tags'
  'bit-docs-tag-sourceref'
  'bit-docs-type-annotate'
)
plugins=(
  'bit-docs-dev'
  'bit-docs-generate-html'
  'bit-docs-glob-finder'
  'bit-docs-js'
)

#
# get local copy of bit-docs-website (will skip/fail if already exists)
#

mkdir "${web}" && git clone "https://github.com/bit-docs/bit-docs-website.git" "${website}"
npm update --prefix "${website}"

#
# clone repos locally (will skip/fail if already exists)
#

mkdir "${tbd}"

for repo in "${devDeps[@]}"
do
  git clone "https://github.com/bit-docs/${repo}.git" "${tbd}/${repo}" && npm install --prefix "${tbd}/${repo}"
done
unset repo

#
# replace devDeps installed by npm with local repos
#

for dir in "${devDeps[@]}"
do
  rm -rf "${website}/node_modules/${dir}"
  ln -s "${tbd}/${dir}" "${website}/node_modules/"
done
unset dir

#
# replace plugins installed by bit-docs with local repos
#

mkdir -p "${node_modules}"

for dir in "${plugins[@]}"
do
    rm -rf "${node_modules}/${dir}"
    ln -s "${tbd}/${dir}" "${node_modules}"
done
unset dir

#
# make sure the bit-docs bin is linked
#

ln -sF '../bit-docs/bin/bit-docs' "${website}/node_modules/.bin/bit-docs"

#
# regenerate website documentation with new local repos
#

npm run bit-docs --prefix "${website}"

#
# start webserver hosting generated site
#

npm install -g http-server && http-server "${website}/gh-pages"

[leoj3n]

This fails for when changing a plugin like bit-docs-prettify that adds scripts to the frontend behind the impossible to know HASH directory inside bit-docs-generate-html. A better strategy using submodules and absolute paths has been espoused since the inception of this script: #11