-
Notifications
You must be signed in to change notification settings - Fork 38
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
696f175
commit 42c3949
Showing
2 changed files
with
88 additions
and
82 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,131 +1,137 @@ | ||
| image:https://github.com/couchbase/docs-sdk-java/actions/workflows/build.yml/badge.svg?branch=release%2F3.4[link="https://github.com/couchbase/docs-sdk-java/actions/workflows/build.yml"] | ||
| image:https://github.com/couchbase/docs-sdk-java/actions/workflows/test-ga.yml/badge.svg?branch=release%2F3.4[link="https://github.com/couchbase/docs-sdk-java/actions/workflows/test-ga.yml"] | ||
| = Couchbase Scala SDK Documentation | ||
|
|
||
| This repository hosts the documentation source for the https://docs.couchbase.com/java-sdk/3.7/hello-world/overview.html[Couchbase Java SDK]. | ||
|
|
||
| = Couchbase Java SDK Documentation | ||
| // Settings: | ||
| ifdef::env-github[] | ||
| :warning-caption: :warning: | ||
| endif::[] | ||
| // URLs: | ||
| :url-org: https://github.com/couchbase | ||
| :url-contribute: https://docs.couchbase.com/home/contribute/index.html | ||
| :url-ui: {url-org}/docs-ui | ||
| :url-playbook: {url-org}/docs-site | ||
| This branch documents the 3.7 release of the SDK. | ||
| It follows the https://docs.couchbase.com/java-sdk/3.7/project-docs/compatibility.html#api-version[SDK 3.6 API]. | ||
|
|
||
| This branch reflects the new Information Architecture for the SDK docs -- this release was previously documented with the old structure (those old docs can be found under the `temp/3.7` branch), and docs with this structure can be seen on the Couchbase docs site for releases 3.6 and earlier. | ||
|
|
||
| This repository hosts the documentation source for the Couchbase Java SDK. | ||
|
|
||
| == Contributing | ||
|
|
||
| Check out our {url-contribute}[contributing guide] to learn how to: | ||
| 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[https://docs.couchbase.com/home/contribute/index.html] (this may still be in the middle of being updated). | ||
|
|
||
| * submit a bug or feedback issue | ||
| * set up your documentation workspace | ||
| * build the documentation | ||
| * submit a pull request | ||
| At a minimum, to build the docs locally, you will need this repo, | ||
| https://github.com/couchbase/docs-sdk-common[docs-sdk-common], | ||
| and the https://github.com/couchbase/docs-server[Server Docs repo] | ||
| in your Antora playbook. | ||
|
|
||
| Thank you for helping to make the documentation better. | ||
| 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. | ||
|
|
||
| == Docs Component Configuration | ||
| TODO: Add in link to new JIRA. | ||
|
|
||
| This repository contains an Antora docs component. | ||
| Keep in mind these key repository features: | ||
|
|
||
| * Component name, version, and start page are configured in each branch's _antora.yml_ file. | ||
| * The navigation for all of the modules is stored in the ROOT module's _nav.adoc_ file. | ||
| * Production branches use the *release/X.Y* naming pattern (e.g., release/2.7, release/3.0). | ||
| ** The {url-playbook}[docs site playbook] instructs Antora to automatically aggregate any branch names that start with *release/*. | ||
| == Notes for Docs Maintainers | ||
|
|
||
| == Documentation Site Toolchain | ||
| The philosophy behind the Information Architecture can be found in the https://docs.couchbase.com/java-sdk/3.6/project-docs/metadoc-about-these-sdk-docs.html[meta doc]. | ||
|
|
||
| The documentation source files are marked up with AsciiDoc. | ||
| Once merged into a version branch, the source files and their assets are aggregated, converted to HTML, and published by Antora to our staging and production sites. | ||
| The docs components and {url-ui}[site UI] are orchestrated by the {url-playbook}[docs site playbook]. | ||
| See the contributing guide to learn more. | ||
| === Directory Structure | ||
|
|
||
| == Documentation Code Sample Testing | ||
| Antora modules used are as follows: | ||
|
|
||
| To ensure that the code samples included in the documentation are correct and produce the results we expect, we have setup scripts that build and test each example file. | ||
| * concept-docs -- discussion docs explaining SDK-relevant aspects of Couchbase; 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. | ||
|
|
||
| For testing we use the https://github.com/bats-core/bats-core[bats-core] automation framework to run the code and https://github.com/ztombol/bats-assert[bats-assert] assertion library to make assertions on the output where necessary. | ||
| 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 the https://github.com/couchbase/docs-sdk-common[sdk-common] repo. | ||
|
|
||
| The tests run against the latest Couchbase Server docker image with the relevant SDK (Java in this case) provided alongside it. | ||
| === Single-sourced Content | ||
|
|
||
| To facilitate running the tests there is a `Makefile` in the `/modules` directory of the project. | ||
| To make maintenance easier for docs of around a dozen SDKs, content that is common across SDK docsets is -- wherever possible -- single-sourced from the https://github.com/couchbase/docs-sdk-common[sdk-common] repo. | ||
|
|
||
| There you will find all the relevant commands needed to execute the docker container and the test/build scripts. | ||
| We recognise that this adds a slight cognitive burden for the new maintainer, but one layer of abstraction seems a reasonable compromise for maintainability. | ||
| To make content re-use workable, certain replaceable attributes are used. | ||
| These are found in the antora.yml file. | ||
|
|
||
| === Running a test | ||
| .Attributes for Single-sourced Content | ||
| |=== | ||
| | Attribute | Use | ||
|
|
||
| Before you can run the tests you will need to ensure you have Docker and npm available on your machine. | ||
| | `server_version:` | ||
| | SDK dotminor releases contain new APIs to match new Server releases. | ||
| This is the release version of Couchbase Server that this SDK release accompanied. | ||
| Not often needed within the SDK documentation -- the server version in `xref` links is set with `version-server:` (see below). | ||
|
|
||
| To run the example tests you will need to build the testing Docker image, run the container and execute your tests. | ||
| | `sdk_current_version:` | Sets the current patch version. | ||
|
|
||
| TIP: After your first build of the docker image you won't need to build it every time you want to run the tests. | ||
| | `sdk_dot_minor:` | The current dotminor. | ||
|
|
||
| Here are the steps required to achieve this: | ||
| | `sdk_dot_major:` | The current major release -- not often needed within the documentation. | ||
|
|
||
| - From the root directory run `make cb-build` to build a local image of Couchbase Server + Java SDK. | ||
| | `version-server:` | This is substituted into `xref` links to the Server, to ensure they land on the correct release version. | ||
|
|
||
| - Once that has completed successfully you can run `make cb-start` to run the docker container. | ||
| | `version-common:` | ||
| | The version (branch) of the single-sourced `sdk-common` repo. | ||
| This is substituted into Antora `include::` directives, to pull in content from the correct branch. | ||
|
|
||
| Note that this can take some time as it will configure Couchbase Server with all the required test data (e.g. travel-sample bucket) for the examples to run successfully. | ||
| | `name_platform:` | Allows us to name the SDK within shared content (*Scala*). | ||
|
|
||
| - If you run `docker ps` in a separate shell you should see a container called `cb-test` running. | ||
| ``` | ||
| CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES | ||
| 6fe1830a205a couchbase:cb7-sdk3-java-ub20 "/entrypoint.sh couc…" About an hour ago Up About an hour 11207/tcp, 11210-11211/tcp, 0.0.0.0:8091-8096->8091-8096/tcp, 18091-18096/tcp cb-test | ||
| ``` | ||
| | `name-sdk:` | Allows us to name the SDK within shared content (*Scala SDK*). | ||
|
|
||
| - Once the container is up you can run `make TEST_NAME="StartUsing.java" single-test` to run an individual test. | ||
| | `sdk_api:` | The API version of this release. | ||
|
|
||
| - You should expect to see the following output in your shell: | ||
| ``` | ||
| ✓ [hello-world] - StartUsing.java [13192] | ||
| | `sdk-api-link:` | Link to the latest API Reference for the SDK. | ||
|
|
||
| 1 test, 0 failures in 13 seconds | ||
| ``` | ||
| | `sdk-gh-link:` | Link to the source code of the SDK. | ||
|
|
||
| - If you want to run all the code sample tests you can also execute `make tests`. | ||
| |=== | ||
|
|
||
| - To stop the docker container you can simply run `make cb-stop`, this will stop and remove the docker container, but will keep the local image should you need to start it up again. | ||
|
|
||
| TIP: Because we mount the project directory in the `cb-test` container, you will see your local code changes reflected in the container instantly, so there is no need to stop and start the container when debugging your code. | ||
| An additional attribute, `page-nav-header-levels: 1`, ensures that the left-hand navigation of the site opens with each topic unfurled by one level. | ||
|
|
||
| === Creating a new test | ||
| === Page Headers | ||
|
|
||
| If you look at the `/modules/test` directory you will find files with the *.bats* extension, which are essentially our test files. | ||
| Each `.adoc` page contains information in the headers: | ||
|
|
||
| Depending on where your code sample is going to be located (e.g. `/modules/devguide`), you will see a corresponding test file in the test directory. | ||
| [source,asciidoc] | ||
| ---- | ||
| = Compatibility | ||
| :description: Platform compatibility, and features available in different SDK versions, and compatibility between Server and SDK. \ | ||
| Plus notes on Cloud, networks, and AWS Lambda. | ||
| :page-aliases: ROOT:overview,ROOT:compatibility-versions-features,compatibility-versions-features | ||
| :page-toclevels: 3 | ||
| :table-caption!: | ||
| ---- | ||
|
|
||
| This is mainly to keep the tests organised and easy to find. | ||
| The `:page-aliases:` directive enables Antora to build 502 redirects -- meaning that inbound links from, for example, old blog posts will still work with the current docset. | ||
|
|
||
| Here is an example test case: | ||
| ``` | ||
| @test "[hello-world] - your-example-file.java" { | ||
| runExample <your-example-class-name> | ||
| assert_success | ||
| assert_output --partial "some assertion substring" | ||
| } | ||
| ``` | ||
| `:page-toclevels:` should be set to `2` to include h3 headers along with h2s in the in-page navigation (right-hand nav). | ||
| Leaving out this directive means that the page will default to `1`, showing only h2 headers in the in-page nav. | ||
| A value of `3` should not be used, save in exceptionally complicated pages like that shown (the https://docs.couchbase.com/scala-sdk/1.6/project-docs/compatibility.html[compatibility page]). | ||
|
|
||
| *runExample* is simply a helper function provided in `test_helper.bash`, which takes care of invoking your `mvn compile exec:java` command. The idea is that any generic test functions can be placed there to be used across any test. | ||
| === Patch Releases | ||
|
|
||
| *assert_success* is a helper function provied by the `bats-assert` library and checks whether your command has successfully exited with a status of 0. | ||
| Update the following files: | ||
|
|
||
| If not, it will fail the test. | ||
| * antora.yml | ||
| * build.gradle | ||
| * modules/devguide/examples/scala/pom.xml | ||
| * modules/project-docs/pages/sdk-release-notes.adoc | ||
|
|
||
| *assert_output --partial* is another bats-assert helper that checks if the output of your code sample contains the substring provided. | ||
| The assertion will fail if the string is not found. | ||
| === New Branches | ||
|
|
||
| Note that it will not always be necessary to assert the output of your code sample, in those cases just using `assert_success` will be enough. | ||
| 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. | ||
|
|
||
| === CI - Github Actions | ||
| === Code Sample Testing | ||
|
|
||
| When submitting a PR, the code sample tests will run against your changes in the same manner as your local machine using Github Actions. | ||
| This is in the process of being changed -- documentation will appear here once this is completed. | ||
|
|
||
| You can see the workflow definitions in the `.github` folder. | ||
|
|
||
| == Docs License | ||
|
|
||
| ©2025 Couchbase, Inc. This work is licensed under CC BY-NC-SA 4.0. | ||
| ©2025 Couchbase, Inc. | ||
| This work is licensed under https://creativecommons.org/licenses/by-nc-sa/4.0/[CC BY-NC-SA 4.0]. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters