package.json

[leoj3n]

See extended commit message details for more information on each commit.

Try it out:

git clone -b package-json-api https://github.com/bit-docs/bit-docs-website.git
cd bit-docs-website
npm install
npm run gen
npm run see

Because this package.json specifies the #file-pathed-deps branches for both bit-docs-generate-html and bit-docs/bit-docs, it is possible to edit the various submodules such as bit-docs-prettify and see the changes by simply running npm run cache-bust && npm run gen (as opposed to having to make a new release on npm or use complicated symlink scripts).

If you ever don't see your changes, try running npm run genf (takes longer; reinstalls everything).

A simple change you can test is to edit docs/modules/bit-docs-prettify/prettify.less to add some background-color to the body:

body {
  background-color: #eee;
}

This will be especially useful for websites that have their own "theme" plugin.

Note that submodules will only be updated once upon initial npm install because of the -f test in the preinstall command:

"preinstall": "[ -f docs/modules/bit-docs/package.json ] || git submodule update --init"

This is done because as you edit submodules they have the unfortunate side effect of throwing error if changes would be overwritten by git submodule update which also can move away from the changes you just made in the working directory (something you wouldn't want to happen upon running npm install a second or third time). The update in the initial git submodule update --init is needed because git submodule init doesn't actually clone things down initially, it just registers the .gitmodules file, so this all is necessary. This shows the caveat of using git submodules in the fact that they are rather hard to work with if you're unfamiliar.

The nice thing about git submodules is that if someone makes a PR with a docs change to for instance bit-docs-prettify, they could also submit a PR to bit-docs-website updating the hash that the submodule is pointing to. I also like how GitHub makes it obvious that docs/modules is meant to be a bunch of sub-repos like "bit-docs-prettify @ 114e4c9" that is also a link to that repo.

There's also git-subtree but that might be even more rare and hard to understand for people.

For some teams, a simple nodejs or bash script that clones the needed git repos into directories that are .gitignored upon initial npm install might be the best option.

Any of these options are better than the current npm install paradigm which has the pitfall of not being able to make changes, immediately test locally, and then commit (unlike the previously mentioned options that integrate with source control) — You could do something like npm install ../path/to/previously/cloned/subrepo but you'll have to do that for each and every plugin or documentation repo you want to work on, and it's manual setup that can be nicely baked-in like with the previously mentioned options.

[chasenlehara]

I don’t 100% understand why using git submodules is better than npm.

The nice thing about git submodules is that if someone makes a PR with a docs change to for instance bit-docs-prettify, they could also submit a PR to bit-docs-website updating the hash that the submodule is pointing to.

This is the same idea that with npm, you could submit a PR that points to your branch, right?

My understanding is that with the related PRs, you can use file: in the package name, so it can point to something locally. So if you’re working locally, then from bit-docs (or whatever) you would point to your local dependency repo, then reinstall from the main repo to see your changes.

Does using git submodules remove the need to install to see your changes?

[leoj3n]

Getting out of the npm dependency paradigm for that express purpose of pulling in documentation to a website using bit-docs as the build tool is helpful, because doing so aids in delineating what is being documented, versus what is an actual dependency of the website itself.

It's also more lightweight, because using npm to pull in the repos needing to be documented will run npm install in each repo, needlessly pulling in adjunct dependencies that will never be used at that level, and duplicating whatever will subsequently be reinstalled all over again at a lower level (in a nested node_modules directory) when bit-docs is executed.

Using npm to pull in repos that need to be documented does not make sense for these reasons; you're just cluttering up the package.json, forcing people to manually clone and link in repos, and causing a bunch of unnecessary top-level dependencies to be installed that will never be used, thus bloating the top-level node_modules directory.

This bit-docs-website repo is a unique case in that it is documenting the same plugins it consumes, which is why it makes sense to have support for file: paths as version strings in package.json.

This might help to clarify further:

As hinted at in the OP, most consumers of bit-docs [+plugins] will probably not use file: to link up dependencies, except for if they have a website theme or custom plugin (that is subsequently included as a submodule, so as to be readily available for modification as needed, by anyone that may clone the website repo). Otherwise, bit-docs (and any plugins) will normally be remote npm dependencies (or bit-docs.dependencies), while whatever is to be documented will most likely be included via git submodule, or download script, or just tracked in the website repo itself.