Use NPM packages for Bootstrap and Font Awesome

[chalin]

As discussed during the 2022-01-31 PSC meeting, we'l be exploring whether we can eliminate the git submodules to Bootstrap and Font Awesome. @geriom has done this for another project. We believe the use of submodules is historical, and docsy use would be simplified if we switched to using NPM packages -- which we're already doing to get Hugo.

[LisaFC]

Would it make sense to see how we get on with the Hugo modules initiative before prioritizing implementing this - it seems if the modules approach takes off we may not need it (I'm not sure how many people absolutely won't be able to use or migrate to modules). Unless it's absolutely trivial, of course.

We use npm for our own user guide Netlify build, but it's not actually our recommended procedure for installing Hugo in our user guide, we just list it as one of several options along with eg Homebrew for Mac - the only thing we actively tell people to install with npm is postcss as I'm not sure there's any other way to do it.

[chalin]

Use of Hugo modules requires use of Go. I don't want to force all of our docsy-dependent projects to use Go. For those projects, I also want the option to continue using docsy via a git submodule -- because that is part of our workflow for many projects.

We confirmed during the PSC meeting that docsy doesn't need BS and FA to be included via submodules. Submodules are a historical artifact that introduces unnecessary complexity. The best (non-Hugo-module) way to include those dependencies is via NPM packages.

Independently of the introduction of Hugo modules, eliminating the git submodules is a very good idea IMHO.

Thoughts?

[LisaFC]

Well let's see if it's a simple change or not - @geriom should be able to check. Agree that a submodule with submodules isn't optimal in terms of managing versions of things etc.

I'm not sure if requiring installing Go as an additional prereq is that onerous compared to everything else we ask users to install (as I mentioned in the meeting I have at least one machine that for boring work reasons I can't install npm on...), though I appreciate some users may not want to do so. Modules is definitely the way Hugo is going, judging by the fact they've (perhaps precipitously) removed all their docs on installing themes as submodules....

[deining]

Use of Hugo modules requires use of Go.

No, that's not true. I just authored #877: follow the instructions given there and you will see that you can easily come up with a skeleton hugo site using docsy as module without go and even without git.

Independently of the introduction of Hugo modules, eliminating the git submodules is a very good idea IMHO.

I fully agree.

What we could do: for each release of Docsy, we could offer not only docsy itself as .zip download, but also the required dependencies. This way, users that don't have to install go, they can add their dependencies via thois download instead. We could even think about adding a dependencies directory _vendor to our repo. Maybe this would even allow for a seamless switch from git submodules to hugo modules without any manual intervention. I'm not sure though that adding a _vendor directory to the repo is a wise decision. The vendor directory takes precedence over any donwloaded module in hugo's module cache, this might not be what everyone wants.

Thoughts?

[chalin]

All: btw, I'm totally ok if the Hugo-modules feature lands before this issue is resolved.

@deining : thanks for correcting my mis-statement -- I'll rephrase my thoughts more carefully when I next have the time, since I'd like to offer a clarification. Quickly though, regarding your proposal: I like the .zip idea, but the projects I'm currently working on require use of docsy via git (with convenient/standard access to dependencies either as submodules or, say, NPM packages).

[chalin]

Here is an example of a project that has moved to using docsy as a submodule with BS+FA fetched as NPM packages: https://github.com/open-telemetry/opentelemetry.io/pull/1164/files.

You can see from the build log that I cleared the cache: https://app.netlify.com/sites/opentelemetry/deploys/6214f7f74484ecf88101d7b3. The site builds just as it did before.

I also did a clean build on my local machine and there are no changes in the generated site files (which is what we want):

$ git clean -xdf
$ rm -Rf themes/docsy
$ npm install
$ npm build
$ (cd public && git diff)
$