This repository hosts the common documentation files for the Couchbase SDKs.
This repository is versioned to track the version of Couchbase Server (e.g., release/7.2, release/7.6, etc). The component version is defined in the component descriptor, antora.yml. References from this repository to pages in the Couchbase Server documentation should mostly stick to this version.
Unlike other documentation repositories that track the Couchbase Server version, this repository is not a hard dependency of the Couchbase Server documentation. Instead, this repository is consumed by the documentation for the language-specific SDKs.
The common SDK component identifies as sdk.
The component name is defined in the component descriptor, antora.yml.
This name should be used in any IDs that refer to files in this repository.
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 Couchbase SDKs.
The shared module contains page fragments, also in the form of partials. These partials hold information common to all the Couchbase 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 SDKs.
One example is the “Sample Application” page, located in this repository at modules/pages/partials/sample-application.adoc. To promote this common page to a concrete page in one of the language-specific SDKs, create the following file in that SDK and populate it with a single include directive, as follows:
include::7.6@sdk:pages:partial$sample-application.adoc[]The include directive effectively imports the common page into a page in the language-specific SDK documentation. Every common page must have a corresponding master page in every language-specific SDK.
All page references in the common page are assumed to be relative to the module in which the page is included (i.e., relative to the master page).
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 master page in the language-specific SDK.
References to all other locations, such as to server, must provide the necessary context (component, version, module, etc).
This repo no longer includes a shared attributes file, modules/pages/partials/attributes.adoc.
Instead, attributes such as the Server version are given in the antora.yml file of each SDK doc repo, and thus automatically included.
This means that some values — such as name-sdk — can be given here in common files, and rendered in each SDK’s docs as the particular SDK name.
Using images in the common folders previously had a workaround, as support for image references outside the current module was not introduced when we started using sdk-common.
This is why older branches use a shared attribute named incimagesdir.
This is no longer necessary, just use
component is sdk, to point back to this repo.
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 understannd 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.
One example is the introduction to views in the file modules/ROOT/pages/view-queries-with-sdk.adoc for a language-specific SDK.
include::6.0@sdk:shared:partial$views.adoc[tag=views-intro]This imports a page fragment that looks like the following:
// tag::views-intro[]
--
The normal CRUD methods allow you to look up a document by its ID.
...
TIP: See xref:7.1@server:understanding-couchbase:views/views-intro.adoc[Views].
--
// end::views-intro[]All the lines between tag::views-intro[] and end::views-intro[] get imported into the page.
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].TODO refresh this section, as we’ve worked around it with each SDK’s attributes in respective antora.yhl files.
©2024 Couchbase, Inc. This work is licensed under CC BY-NC-SA 4.0.