[CB-13925] Making file fetch happen on every build.

[dblotsky]

• Making gulpfile.js always fetch fetched files on build.
• Adding --nofetch option to gulpfile.js, which skips fetching.
• Improving error message in augment_toc.js a bit.

Platforms affected

None. It's a docs change.

What does this PR do?

Fixes CB-13925.

What testing has been done on this change?

Built the docs site locally.

Checklist

• Reported an issue in the JIRA database
• Commit message follows the format: "CB-3232: (android) Fix bug with resolving file paths", where CB-xxxx is the JIRA ID & "android" is the platform affected.
• Added automated test coverage as appropriate for this change.

[janpio]

Will this only affect dev when run in CI?

[dblotsky]

@janpio this change will not retroactively download files for any languages or versions other than en/dev. Is that what you mean?

[janpio]

Yes, just tried to understand on what "scope" this change affects the docs (as it is all undocumented).

[dblotsky]

@janpio got it. In general, it's unlikely that details like these will ever be documented because they're in code, and they change. I can e-meet with you to give you a full exposé of the codebase (it's not that much, actually). Might you find that helpful?

[janpio]

Telling me won't change the fact that anyone who jumps into the codebase (or even just content) will have the same problem of not knowing which "processes" and tasks there are - which is quite different to the technical details of the implementation.

In this case something like this:

There is a fetch task in gulpfile.js (which triggers tools/bin/fetch_docs.js internally) that pulls in external documentation (plugins READMEs) into the dev folder.

[janpio]

Now "documented" at https://github.com/apache/cordova-docs/blob/master/doc/working-on-docs.md#pull-in-documentation-from-other-repos

[dblotsky]

@janpio if you want to know which tasks there are, you run gulp, and it prints out a whole page describing itself. It's already documented, exactly at the point where you would need the doc: when you use the build system.

Moreover, I think if you want to work on the docs system (not just modifying contents of the docs), you do need to know the implementation. For example that extra doc section does describe the implementation, since you never actually need to run gulp fetch, the same way you never run gulp styles. It runs automatically, as part of the build dependency graph.

Since you and @stevengill have been working on the docs a fair bit, I thought it might be useful for me to pass some of the implementation knowledge to you (because reading the code is less efficient, but still just as informative). I also think because you folks are working on this, you might have more opportunities to document the implementation than I will. However, I could try and find some time to document this in the next few months if you think it will be valuable.