search

boostorg / website-v2-docs

Boost Site Documentation
https://docs.cppalliance.org
Boost Software License 1.0
6 stars 24 forks source link

README workflow is missing gulp installation #52

Closed anarthal closed 1 year ago

anarthal commented 1 year ago

Which documentation does this apply to? Repo README

I followed the README and was getting this error

gulp is not installed
[21:55:56.110] FATAL (antora): Specified UI bundle does not exist: /home/ruben/workspace/site-docs/antora-ui/build/ui-bundle.zip (resolved from url: ./antora-ui/build

Solved by npm -g install gulp. Could gulp be added as dependency in package.json?

alandefreitas commented 1 year ago

Oh... the instructions came before "the merge" we apply to docs only. When we merged all site-docs and antora-ui also became part of the project, gulp became an undocumented dependency.

I don't know if it's a good idea to have gulp in package.json. I really don't know. In a way, gulp seems like something people install globally, so this step should be documented. On the other hand, antora is in package.json, so installing antora could also be removed from the docs if we go this route.

We need to research this a little better.

anarthal commented 1 year ago

I tend to advocate for package.json, because 1) simpler and 2) more reproducible (you've tested in your local env with gulp version x, you ensure that this version is the one you get). There may be considerations I'm not seeing though.

alandefreitas commented 1 year ago

Yes. We could include gulp in package.json and remove antora itself from the instructions, since it's also already in package.json.

alandefreitas commented 1 year ago

It seems like ChatGPT agrees with you.

Is it usual to have gulp listed in package.json or is it always installed globally?

ChatGPT It is common to have gulp listed as a dependency in the package.json file of a project and installed locally, rather than globally. This is because it allows for greater consistency in the development environment, ensuring that all developers working on the project are using the same version of gulp and any other dependencies required for the project. Additionally, by including gulp as a project dependency, it allows for easier installation and setup of the project, as other developers can simply run npm install to install all the necessary dependencies.

That being said, gulp can also be installed globally, and this may be preferred in some cases, such as when you need to use gulp across multiple projects or want to make it available system-wide. However, it is generally recommended to use local installations whenever possible to avoid conflicts between different versions of gulp or other dependencies.