You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository hosts the documentation source for the Couchbase Java SDK.
18
-
19
-
== Contributing
20
-
21
-
Check out our {url-contribute}[contributing guide] to learn how to:
22
-
23
-
* submit a bug or feedback issue
24
-
* set up your documentation workspace
25
-
* build the documentation
26
-
* submit a pull request
27
-
28
-
Thank you for helping to make the documentation better.
29
-
30
-
== Docs Component Configuration
31
-
32
-
This repository contains an Antora docs component.
33
-
Keep in mind these key repository features:
34
-
35
-
* Component name, version, and start page are configured in each branch's _antora.yml_ file.
36
-
* The navigation for all of the modules is stored in the ROOT module's _nav.adoc_ file.
37
-
* Production branches use the *release/X.Y* naming pattern (e.g., release/2.7, release/3.0).
38
-
** The {url-playbook}[docs site playbook] instructs Antora to automatically aggregate any branch names that start with *release/*.
39
-
40
-
== Documentation Site Toolchain
41
-
42
-
The documentation source files are marked up with AsciiDoc.
43
-
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.
44
-
The docs components and {url-ui}[site UI] are orchestrated by the {url-playbook}[docs site playbook].
45
-
See the contributing guide to learn more.
46
-
47
-
== Documentation Code Sample Testing
48
-
49
-
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.
50
-
51
-
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.
52
-
53
-
The tests run against the latest Couchbase Server docker image with the relevant SDK (Java in this case) provided alongside it.
54
-
55
-
To facilitate running the tests there is a `Makefile` in the `/modules` directory of the project.
56
-
57
-
There you will find all the relevant commands needed to execute the docker container and the test/build scripts.
58
-
59
-
=== Running a test
60
-
Before you can run the tests you will need to ensure you have Docker and npm available on your machine.
61
-
62
-
To run the example tests you will need to build the testing Docker image, run the container and execute your tests.
63
-
64
-
TIP: After your first build of the docker image you won't need to build it every time you want to run the tests.
65
-
66
-
Here are the steps required to achieve this:
67
-
68
-
- `cd` into the `/modules` directory and run `make cb-build` to build a local image of Couchbase Server + Java SDK.
69
-
70
-
- Once that has completed succesfully you can run `make cb-start` to run the docker container.
71
-
72
-
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.
73
-
74
-
- If you run `docker ps` in a separate shell you should see a container called `cb-test` running.
75
-
```
76
-
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
77
-
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
78
-
```
79
-
80
-
- Once the container is up you can run `make TEST_NAME="StartUsing.java" single-test` to run an individual test.
81
-
82
-
- You should expect to see the following output in your shell:
83
-
```
84
-
✓ [hello-world] - StartUsing.java [13192]
85
-
86
-
1 test, 0 failures in 13 seconds
87
-
```
88
-
89
-
- If you want to run all the code sample tests you can also execute `make tests`.
90
-
91
-
- 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.
92
-
93
-
TIP: Because we mount the `/modules` 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.
94
-
95
-
=== Creating a new test
96
-
If you look at the `/modules/test` directory you will find files with the *.bats* extension, which are essentially our test files.
97
-
98
-
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.
99
-
100
-
This is mainly to keep the tests organised and easy to find.
*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.
112
-
113
-
*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.
114
-
115
-
If not, it will fail the test.
116
-
117
-
*assert_output --partial* is another bats-assert helper that checks if the output of your code sample contains the substring provided.
118
-
The assertion will fail if the string is not found.
12
+
This branch is a proof of concept to see whether it is possible to include resources (in this case, example files) from an older version of an Antora component without including any pages from that version in the build.
119
13
120
-
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.
14
+
See https://couchbase.slack.com/archives/C050L6VP5CP/p1761228893550229[this Slack thread] for background discussion.
121
15
122
-
=== CI - Github Actions
123
-
When submitting a PR, the code sample tests will run against your changes in the same manner as your local machine using Github Actions.
16
+
Testing showed that the examples from the older version are included in the build 🎉.
17
+
However, the older version number (where the files originated) is still included in the version switcher drop-down, even though that older version doesn't contain any pages 😢.
124
18
125
-
You can see the workflow definitions in the `.github` folder.
19
+
See https://github.com/couchbase/docs-server/pull/3944[] for a pull request that tests this proof of concept, including a `preview` config file which references this branch.
0 commit comments