ENT-14128: Made autolinking fail loudly, added script to build locally, and fixed broken links and other build issues

[olehermanse]

Ticket: ENT-14128

[olehermanse]

@cf-bottom jenkins, please

[cf-bottom]

Alright, I triggered a build:

Jenkins: https://ci.cfengine.com/job/fast-build-and-deploy-docs-master/42/

Documentation: http://buildcache.cfengine.com/packages/build-documentation-pr/jenkins-fast-build-and-deploy-docs-master-42/output/_site/

[olehermanse]

@cf-bottom jenkins

[cf-bottom]

Alright, I triggered a build:

Jenkins: https://ci.cfengine.com/job/fast-build-and-deploy-docs-master/77/

Documentation: http://buildcache.cfengine.com/packages/build-documentation-pr/jenkins-fast-build-and-deploy-docs-master-77/output/_site/

[olehermanse]

@cf-bottom jenkins, please

[cf-bottom]

Sure, I triggered a build:

Jenkins: https://ci.cfengine.com/job/fast-build-and-deploy-docs-master/82/

Documentation: http://buildcache.cfengine.com/packages/build-documentation-pr/jenkins-fast-build-and-deploy-docs-master-82/output/_site/

[aleksandrychev]

nice work

[nickanderson]

Seemed ok to me, one of my ai friends says:

  - Fence logic is now hand-duplicated in 3 places (cfdoc_linkresolver.applyLinkMap, cfdoc_references_resolver.process, cfdoc_macros.prune_include_lines) with slight variations. It's correct in each, but it's the kind of thing that drifts. A small shared generator (for line, in_pre 
  in iter_fence_state(lines)) would de-risk future edits. Non-blocking.
  - Ambiguous titles resolve silently to whichever page parsed last. There are two pages titled Installing CFEngine and two titled Promises. load_references builds a dict keyed by lowercased ref, so the last-appended URL wins with no warning. The applyLinkMap path does emit a
  "Multiple link targets" warning for backtick autolinks, but the [text][ref] path doesn't. Since this PR is specifically about making link resolution trustworthy, it'd be a natural place to also warn on duplicate-title collisions — though it's a pre-existing quirk, fine to defer.
  - build-locally.sh clones over SSH (git@github.com:). Contributors without GitHub SSH keys will fail at step 1. An HTTPS fallback (or a one-line note in the header comment) would help. The --exclude='/tmp/' to stop rsync recursing into its own output dir is a nice catch.
  - Minor comment nit: _no_links.md's header says "Lines starting with <!--/blank lines are ignored," but the parser actually strips full <!-- ... --> blocks via re.DOTALL — i.e. it's more robust than documented. Trivial.

[craigcomstock]

this looks like the same comment as in generator/_scripts/cfdoc_linkresolver.py might be nice to refactor at some point.

[olehermanse]

#3693