Skip to content

Doc 14675 fix Antora build errors (with Claude) - #4162

Open
osfameron wants to merge 6 commits into
release/8.0from
DOC-14675-fix-antora-errors
Open

Doc 14675 fix Antora build errors (with Claude)#4162
osfameron wants to merge 6 commits into
release/8.0from
DOC-14675-fix-antora-errors

Conversation

@osfameron

Copy link
Copy Markdown
Collaborator

This PR fixes 62 of the 81 Antora build errors that were showing up for server 8.0 (typo'd link targets, :// module-separator mistakes, .html used where .adoc was needed, browser-fragment junk pasted into xrefs, an orphaned page, etc.).

Done using Claude 🤖 so does need some testing. Done by feeding the latest antora.log from a live build to get Actual Errors. I gave it https://docs-staging.couchbase.com/site-dependencies.json to allow it to resolve links to server 8.0 that are actually in other repositories, and pointed it at docs-sync-gateway.

I've verified the PR by:

  • eyeballing each hunk in the PR diff to see if:
  • there is an obvious mistake (.adoc without [], .html[], typo, etc.)
  • there is a subtle Asciidoc mistake that I recognize and discussed with Claude
  • if there's no obvious mistake, I've opened the page on live to verify that the link is broken currently.
  • ... i.e. I did NOT check that the new link is correct, I think server writers are better placed to weigh in on this!

Remaining errors not fixed

The remaining 19 all need a documentation/product decision rather than a mechanical fix: (Claude's wording below, apologies if any of the reasoning is incorrect, I've not verified. But the errors in the logs are real!)

  1. FTS pages deleted in 2022 "redundant pages cleanup" (3 errors) cbft-bleve-moss.adoc, fts-search-response.adoc, manage-ui.adoc link to fts-queries.adoc, fts-consistency.adoc, fts-searching-from-the-ui.adoc — all removed years ago, content folded elsewhere. Needs someone to find/confirm the right current target for each.

  2. compaction-rest-api.adoc split into three pages (2 errors) storage-settings.adoc and expiration.adoc both want a single "Compaction API" link, but that page is now three separate pages (rest-compact-post.adoc, rest-autocompact-global.adoc, rest-autocompact-per-bucket.adoc) with no overview page. Needs a call on which one (or whether to link all three).

  3. Missing n1ql-rest-settings example includes (4 errors) general-settings.adoc includes 4 example files (query-settings-post-*.sh/json) from the cb-swagger repo's n1ql-rest-settings module, but that module has no examples/ directory at all. Looks like a generation-pipeline gap (cb-swagger has a Gradle/OpenAPI bundle step that may not be running), not a content typo — probably one for whoever owns that build.

  4. Missing cbdocloader page + nav partial (1 error) nav.adoc includes tools:partial$nav-cbdocloader.adoc. Traced this to Nov 2021: docs-server deleted its own cbdocloader-tool.adoc and switched to including a partial from the backup repo's new tools module — but that partial (and the cbdocloader.adoc page itself) was never actually created there. Its siblings (nav-cbdatarecovery, nav-cbexport, nav-cbimport) all exist and work. This needs someone with access to the backup repo to author the missing page + nav partial.

  5. docs-operator restructure (3 errors) couchbase-cloud-deployment.adoc links to operator:ROOT:install-gke.adoc, install-eks.adoc, install-aks.adoc. Traced to a "K8S-1268: Reorganize Docs" restructure in docs-operator — pages are gone, no obvious 1:1 successor found. Needs someone who knows the current operator docs structure.

  6. Pinned SDK versions no longer resolving (5 errors) try-a-query.adoc (3.0@python-sdk), extended-attributes-fundamentals.adoc (3.4@java-sdk), scopes-and-collections.adoc (3.3@java-sdk, ×3). Oddly, the target pages and branches (release/3.0, release/3.4, release/3.3) do still exist in the SDK repos — so this probably isn't a dead link so much as this site build's playbook not including those particular old SDK version branches. Worth checking against whichever playbook is live, or just bumping these to a current SDK version.

  7. Orphaned tutorial link (1 error) intro.adoc's "Developer Bootstrap Exercises" tile links to tutorials:quick-start:quickstart-docker-image-manual-cb65.adoc — a Couchbase 6.5-era Docker quickstart that no longer exists anywhere in docs-devex's tutorials module, and there's no obvious current tutorial that replaces it. Needs a call on whether to relink it to something else or just drop the tile.

osfameron and others added 6 commits September 8, 2026 13:16
Resolves a batch of Antora build errors surfaced for the server 8.0
component-version: typo'd link targets, `:` vs `/` module-separator
mistakes, `.html` used where `.adoc` was needed, bare same-directory
xrefs missing their subdirectory, a couple of browser "copy link to
highlighted text" fragments pasted in as xref targets, and one image
referenced from the wrong module.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- rest-bucket-create.adoc: two xrefs to xdcr-enable-crossclusterversioning.adoc
  were missing the `learn:` module prefix
- rotate-encryption-at-rest-key.adoc / drop-encryption-deks.adoc: xrefs used
  `manage:security/...` instead of `manage:manage-security/...`
- recover-data-with-xdcr.adoc: `add-a-node-and-rebalance.adoc` doesn't exist;
  real page is `add-node-and-rebalance.adoc`
- fts-system-indexes.adoc: xref used a filesystem-style path
  (`n1ql/pages/n1ql-language-reference/searchfun.adoc`) instead of proper
  xref syntax (`n1ql:n1ql-language-reference/searchfun.adoc`)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- intro.adoc / starter-kits.adoc: each had a stray duplicate doctitle
  (level-0 heading) left over below the page attributes; removed the
  second one.
- rbac.adoc / authentication-domains.adoc: `[backup-restore]` and
  `[saml-authentication]` used single brackets, which Asciidoctor
  treats as a section *style* rather than an anchor - this makes the
  section a "special section" that can't contain nested subsections.
  Changed to double brackets (`[[id]]`) so they're proper anchors.
  authentication-domains.adoc's anchor is actively linked from
  authentication-overview.adoc and configure-saml.adoc, so it had to
  be preserved rather than deleted.

Verified locally with `asciidoctor` that both error types are gone
and no new warnings were introduced.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Three xrefs into the sync-gateway component were broken:
- `sync-gateway:refer/config-properties.adoc` -- that path was renamed;
  `configuration-properties-legacy.adoc` carries a page-alias for it,
  confirming this is the real successor page, so linking directly to
  it rather than relying on alias resolution.
- Two uses of `sync-gateway::get-started-prepare.adoc` (double-colon,
  targeting the ROOT module) -- the real page lives in the
  `start-here` module, so the module name was missing.
- One of those also targeted `#step-1create-a-bucket`, an anchor that
  never existed on the target page. Added a real anchor
  (`#lbl-create-bucket`) to docs-sync-gateway itself, matching that
  page's existing anchor-naming convention, and pointed this xref at
  it instead of guessing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Target page `install:upgrade-online.adoc` was deleted years ago.
Sibling pages (upgrade-cluster-online-full-capacity.adoc,
upgrade-cluster-online-reduced-capacity.adoc) already link to the
correct successor and anchor: upgrade-procedure-selection.adoc#swap-rebalance.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@osfameron

Copy link
Copy Markdown
Collaborator Author

@ggray-cb oh, we did a drive-by on some of your links with :~:text= in them (to trigger the Chrome specific highlighting). It looks from Git history like you added those a "hacky link" to some API docs?

Deleted only because the link itself was broken. Feel free to re-add them (to this PR branch) if you like.
Alternatively if you've had chance to look at the new Highlight feature on Staging, that will be more robust (it's cross browser, using mark.js) so it might be worth waiting for that, and then rewriting these (and the remaining 3 or so that we left untouched.)

@TimLFletcher TimLFletcher left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks pretty common sense to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants