This repository hosts the common documentation source for the Couchbase Analytics SDK Documentation.
This branch contains common documents and document fragments for the 1.0 API release of each Analytics SDK. It follows the Analytics SDK 1.0 API.
Contributions are welcome! Please test them locally, and then submit a pull request. A guide to using asciidoc, building Antora locally, and working with our repos can be found at https://docs.couchbase.com/home/contribute/index.html (this may still be in the middle of being updated).
At a minimum, to build the docs locally, you will need:
-
This repo, docs-analytics-sdk-common,
-
One of the actual Analytics SDK repos, such as docs-analytics-sdk-common,
-
And the Server Docs repo
in your Antora playbook.
If you are not sure the best way to update the docs, please raise a JIRA ticket with your suggestion, putting in as much information as possible. You can do this by clicking on the Leave Feedback button on any of the docs pages — usually found near the top right of the page.
Alternatively, raise a GitHub issue in this repository.
Antora modules used for each SDK’s repo are as follows:
-
concept-docs — discussion docs explaining SDK-relevant aspects of Couchbase & Analytics; in the published docs these are now interleaved with the howtos, rather than in a separate section. This module also contains the mini landing pages which introduce each section.
-
devguide/examples — the home of all code examples.
-
hello-world — overview (landing page) and the introductory tutorials.
-
howtos — practical explanations, with plenty of code snippets. These are the docs used by the majority of developers.
-
project-docs — deployment section. Docs that you need to use the software (compatibility tables, release notes, etc.), but which are not about the software API.
-
ref — reference material, such as error codes and client settings.
-
ROOT — contains
nav.adoc, the navigation file for this component.
Within each module, docs content is mostly found in the pages directories, as .adoc files.
Occasionally, a partial fragment in a partials directory contains content reused over more than one page.
Most re-use is from single-sourced content in from this sdk-common repo. Here, the content is divided between partials and full pages, in the manner described below.
The files and directories in this repository are organized as an auxilary Antora documentation component. That means this repository doesn’t contribute any pages to the documentation directly. Instead, it provides a) partial files (both complete pages and page fragments) which can be included into pages from another component and b) shared images that those pages can reference.
At a high level, this repository contains two modules, which serve two distinct purposes:
-
pages
-
shared
The pages module (not to be confused with Antora’s pages folder), contains complete pages in the form of partials. These partials are the common pages shared by all the Columnar SDKs.
The shared module contains page fragments, also in the form of partials. These partials hold information common to all the Analytics SDKs, but which do not constitute complete pages.
The pages module has the following structure starting from the root of the repository:
modules/
pages/
partials/
*.adoc
assets/
images
*.png
Although the AsciiDoc files are located in the partials folder, they are, in fact, complete pages. The only reason they’re located in the partials folder is so that they don’t get turned into pages directly. Instead, they need to be included into pages in the language-specific Analytics SDKs.
Using images in the common folders is a little tricky because Antora doesn’t yet support image references outside the current module (nor does the include cause the context to change). Therefore, it’s necessary to employ a workaround.
To workaround this limitation in Antora, the location of images in common pages is controlled using a shared attribute named incimagesdir.
Here’s how you’ll use it to specify the location of images in these common pages:
image::{incimagesdir}/travel-app-narration.png[]This is the only time in Antora you would use an attribute reference at the start of an image target.
The incimagesdir attribute is defined in the attributes file, modules/pages/partials/attributes.adoc.
The value of this attribute refers to the relative path to the images folder in the pages module (though it has to do a bit of a reach to get there).
You don’t have to worry about any of these details as long as you prefix the image target with {incimagesdir} for now.
The shared module has the following structure starting from the root of the repository:
modules/
shared/
partials/
*.adoc
This module is a little easier to understandn because it contains partials which really are partials (i.e., page fragments). These partials can be included into any page in the language-specific SDK documentation to provide shared content such as reference sections, explanations, definitions, phrases, etc.
Although not required, the content in these partials is often selected using a tag or tags.
Like the common pages, all page references in shared partials are assumed to be relative to the module in which the partial is included.
Thus, the reference xref:n1ql-query.adoc[Querying with SQL+]+ refers to the n1ql-query.adoc page in the same module as sample-application.adoc in the language-specific SDK.
References to all other locations, such as to server, must provide the necessary context (component, version, module, etc).
Unlike the common pages, the partials do not import a shared attributes file. That’s because partials can be included partially and thus bypass attributes defined in the document header. Unfortunately, that means that the references in the share partials to the server have to be hard-coded for now.
See xref:7.1@server:understanding-couchbase:views/views-intro.adoc[Views].Production branches use the release/x.y naming pattern (e.g. release/3.7, release/3.6).
Antora uses the branch names in the playbook, but also uses the version given in the antor.yml file, to create the version navigation — so this version number must be unique within the repo for any branches included in the playbook.
When creating a new branch for a new release, remember to update the antora.yml file before trying to build.
©2025 Couchbase, Inc. This work is licensed under CC BY-NC-SA 4.0.