Skip to content

Commit b9fc4c6

Browse files
RichardSmedleyRichardSmedley
committed
--> new SDK docs IA
1 parent 62595cc commit b9fc4c6

File tree

1 file changed

+98
-86
lines changed

1 file changed

+98
-86
lines changed

‎README.adoc‎

Lines changed: 98 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,135 @@
11
= Couchbase Python SDK Documentation
2-
// Settings:
3-
ifdef::env-github[]
4-
:warning-caption: :warning:
5-
endif::[]
6-
// URLs:
7-
:url-org: https://github.com/couchbase
8-
:url-contribute: https://docs.couchbase.com/home/contribute/index.html
9-
:url-ui: {url-org}/docs-ui
10-
:url-playbook: {url-org}/docs-site
11-
12-
This repository hosts the documentation source for the Couchbase Python SDK.
2+
3+
This repository hosts the documentation source for the https://docs.couchbase.com/python-sdk/4.6/hello-world/overview.html[Couchbase Python SDK].
4+
5+
This branch documents the 4.6 release of the SDK.
6+
It follows the https://docs.couchbase.com/python-sdk/4.6/project-docs/compatibility.html#api-version[SDK 3.9 API].
7+
8+
This branch reflects the new Information Architecture for the SDK docs.
9+
1310

1411
== Contributing
1512

16-
Check out the {url-contribute}[contributing guide] to learn how to:
13+
Contributions are welcome!
14+
Please test them locally, and then submit a pull request.
15+
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).
1716

18-
* submit a bug or feedback issue
19-
* set up your documentation workspace
20-
* build the documentation
21-
* submit a pull request
17+
At a minimum, to build the docs locally, you will need this repo,
18+
https://github.com/couchbase/docs-sdk-common[docs-sdk-common],
19+
and the https://github.com/couchbase/docs-server[Server Docs repo]
20+
in your Antora playbook.
2221

23-
Thank you for helping to make the documentation better.
22+
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.
2423

25-
== Docs Component Configuration
2624

27-
This repository contains an Antora docs component.
28-
Keep in mind these key repository features:
25+
== Notes for Docs Maintainers
2926

30-
* Each branch's _antora.yml_ file configures the component name, version, and start page.
31-
* The ROOT module's _nav.adoc_ file stores the navigation for all of the modules.
32-
* Production branches use the *release/X.Y* naming pattern (for example, release/5.5, release/6.0).
33-
** The {url-playbook}[docs site playbook] instructs Antora to automatically aggregate any branch names that start with *release/*.
27+
The philosophy behind the Information Architecture can be found in the https://docs.couchbase.com/python-sdk/4.6/project-docs/metadoc-about-these-sdk-docs.html[meta doc].
3428

35-
== Documentation Site Toolchain
29+
=== Directory Structure
3630

37-
The documentation source files written with AsciiDoc markup.
38-
Once merged into a version branch Antora aggregates the source files and their assets, converts to HTML, and publishes them to the staging and production sites.
39-
The {url-playbook}[docs site playbook] orchestrates the docs components and {url-ui}[site UI].
40-
See the contributing guide to learn more.
31+
Antora modules used are as follows:
4132

42-
== Automated Testing
33+
* 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.
34+
This module also contains the mini landing pages which introduce each section.
35+
* devguide/examples -- the home of all code examples.
36+
* hello-world -- overview (landing page) and the introductory tutorials.
37+
* howtos -- practical explanations, with plenty of code snippets.
38+
These are the docs used by the majority of developers.
39+
* project-docs -- deployment section.
40+
Docs that you need to use the software (compatibility tables, release notes, etc.), but which are not about the software API.
41+
* ref -- reference material, such as error codes and client settings.
42+
* ROOT -- contains `nav.adoc`, the navigation file for this component.
4343

44-
This repository performs a check on the sample code upon opening a Pull Request.
45-
These tests need to succeed to perform the merge.
44+
Within each module, docs content is mostly found in the `pages` directories, as `.adoc` files.
45+
Occasionally, a partial fragment in a `partials` directory contains content reused over more than one page.
46+
Most re-use is from single-sourced content in the https://github.com/couchbase/docs-sdk-common[sdk-common] repo.
4647

47-
=== Test Framework Structure
48+
=== Single-sourced Content
4849

49-
image::TestInfra.png[]
50+
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.
5051

51-
The following steps conduct the check:
52+
We recognise that this adds a slight cognitive burden for the new maintainer, but one layer of abstraction seems a reasonable compromise for maintainability.
53+
To make content re-use workable, certain replaceable attributes are used.
54+
These are found in the antora.yml file.
5255

53-
1. The user opens a PR, triggering the GitHub Action
54-
2. The action creates a GitHub runner VM, and copies the repository over
55-
3. The runner starts the Docker test framework with `docker compose --profile prod up --abort-on-container-exit`. The flag is to verify the database container is also killed when the tests finish.
56-
4. The database and SDK containers start. The following two steps occur concurrently.
57-
** Database Container: Uses the `server/sandbox` image from Docker Hub. This image configures and starts Couchbase, setting up a one node cluster with the travel-sample bucket installed.
58-
** SDK Container: Builds the SDK image from a debian python base image, copying the repository over, and installing dependencies. It then uses `wait-for-couchbase` to ping the Couchbase container, until it confirms the database is fully configured and running.
59-
5. Once the SDK confirms the database is ready for tests, it runs the bats test file. Bats retries each test up to three times upon failure.
60-
6. When the tests have completed, both the SDK and Couchbase containers should die. If they persist, such as in a case where the test framework crashes, the GitHub Action instead destroys them.
56+
.Attributes for Single-sourced Content
57+
|===
58+
| Attribute | Use
6159

62-
=== Testing Code Samples Locally
60+
| `server_version:`
61+
| SDK dotminor releases contain new APIs to match new Server releases.
62+
This is the release version of Couchbase Server that this SDK release accompanied.
63+
Not often needed within the SDK documentation -- the server version in `xref` links is set with `version-server:` (see below).
6364

64-
You may want to run tests locally if you are adding/updating a code sample.
65-
The only prerequisites are a local copy of this repository, and https://www.docker.com/[Docker].
66-
You can start the local test environment by running the following command:
65+
| `sdk_current_version:` | Sets the current patch version.
6766

68-
[source, console]
69-
----
70-
docker compose --profile local up
71-
----
67+
| `sdk_dot_minor:` | The current dotminor.
7268

73-
This creates two Docker containers with the same structure as described in <<Test Framework Structure>>, with the following changes:
69+
| `sdk_dot_major:` | The current major release -- not often needed within the documentation.
7470

75-
* The bats tests aren't automatically performed once Couchbase has finished configuring
76-
* The repository files in the container mount onto the SDK repository in your local machine.
77-
This means any changes you make to the files on your local machine are instantly reflected in the container.
71+
| `version-server:` | This is substituted into `xref` links to the Server, to ensure they land on the correct release version.
7872

79-
To run tests, you either need to use the
80-
https://docs.docker.com/desktop/use-desktop/container/#integrated-terminal[Integrated Terminal]
81-
feature on Docker Desktop, or SSH into the container from the command line.
82-
You can use the following command to use the SDK container shell:
73+
| `version-common:`
74+
| The version (branch) of the single-sourced `sdk-common` repo.
75+
This is substituted into Antora `include::` directives, to pull in content from the correct branch.
8376

84-
[source, console]
85-
----
86-
docker exec -it python-sdk-local /bin/bash
87-
----
77+
| `name_platform:` | Allows us to name the SDK within shared content (*Python*).
8878

89-
Once within the container, run the following command to run a single test:
79+
| `name-sdk:` | Allows us to name the SDK within shared content (*Python SDK*).
9080

91-
[source, console]
92-
----
93-
bats -f "<test_name>" test.bats
94-
----
81+
| `sdk_api:` | The API version of this release.
9582

96-
The `-f` flag only runs tests that match the given regular expression.
97-
As test names are in a standard format, you can also run the following to test all the files in a given module:
83+
| `sdk-api-link:` | Link to the latest API Reference for the SDK.
9884

99-
[source, console]
100-
----
101-
bats -f "<module name>" test.bats
102-
----
85+
| `sdk-gh-link:` | Link to the source code of the SDK.
10386

104-
=== Creating a New Test
87+
|===
10588

106-
To add a new test, append the following to the `test.bats` file.
10789

108-
[source, bats]
90+
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.
91+
92+
=== Page Headers
93+
94+
Each `.adoc` page contains information in the headers:
95+
96+
[source,asciidoc]
10997
----
110-
@test "[<module>] - <code_file>" {
111-
runExample $<module_dir_var> <code_file>
112-
assert_success
113-
}
98+
= Compatibility
99+
:description: Platform compatibility, and features available in different SDK versions, and compatibility between Server and SDK. \
100+
Plus notes on Cloud, networks, and AWS Lambda.
101+
:page-aliases: ROOT:overview,ROOT:compatibility-versions-features,compatibility-versions-features
102+
:page-toclevels: 3
103+
:table-caption!:
114104
----
115105

116-
You can find the module directory variables in `test_helper.bash`.
117-
The test name is `"[<module>] - <code_file>"`.
118-
The name can be anything, but this standard format allows you to carry out single tests, as described in the preceding section.
119-
For more information about creating tests, see the https://bats-core.readthedocs.io/en/stable/writing-tests.html[bats documentation].
106+
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.
107+
108+
`:page-toclevels:` should be set to `2` to include h3 headers along with h2s in the in-page navigation (right-hand nav).
109+
Leaving out this directive means that the page will default to `1`, showing only h2 headers in the in-page nav.
110+
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]).
111+
112+
=== Patch Releases
113+
114+
Update the following files:
115+
116+
* antora.yml
117+
* build.gradle
118+
* modules/devguide/examples/scala/pom.xml
119+
* modules/project-docs/pages/sdk-release-notes.adoc
120+
121+
=== New Branches
122+
123+
Production branches use the *release/x.y* naming pattern (e.g. `release/3.10`, `release/3.9`).
124+
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.
125+
When creating a new branch for a new release, remember to update the antora.yml file before trying to build.
126+
127+
=== Code Sample Testing
128+
129+
This is in the process of being changed -- documentation will appear here once this is completed.
130+
120131

121132
== Docs License
122133

123-
©2025 Couchbase, Inc. This work is licensed under CC BY-NC-SA 4.0.
134+
©2026 Couchbase, Inc.
135+
This work is licensed under https://creativecommons.org/licenses/by-nc-sa/4.0/[CC BY-NC-SA 4.0].

0 commit comments

Comments
 (0)