The Couchbase documentation is stored in multiple repositories that are organized in a standard directory structure.
The Couchbase documentation is stored several organizations and multiple repositories on GitHub. The following repositories accept contributions via the regular workflow and use a standard branch pattern.
Some Couchbase repositories only accept contributions via Gerrit, use custom branch patterns, and have additional content and AsciiDoc requirements. Review the project’s README for the latest contributing requirements, and contact the project lead before working on documentation stored in these repositories.
The CLI repository uses the Gerrit workflow and custom branch patterns. Additionally, the AsciiDoc files in this repository are used to create two sets of documentation:
The CLI pages incorporated in the Couchbase Server component.
Standalone man pages that are bundled with the Server software.
When editing these files, use the man page section structure and formatting.
Some Couchbase repositories are private. Only Couchbase employees can contribute to the documentation in these components.
The Backup repository uses the Gerrit workflow and custom branch patterns. Like the CLI repository, this repository is used to create the Backup pages in the Couchbase documentation, and standalone man pages.
The Autonomous Operator repository uses the Gerrit workflow and custom branch patterns.
The Analytics service documentation uses the Gerrit workflow. It is maintained in collaboration with the AsterixDB project.
The Couchbase repositories that contain documentation use a standard directory structure and nomenclature. This ensures that Antora can locate the documentation components, collect the content files, and then build docs.couchbase.com.
A documentation component contains AsciiDoc files, their optional assets and examples, one or more optional navigation files, and a component descriptor file per repository. All of the files in a component are versioned together.
While it is common to find all of a component’s files in a single repository, a component can be distributed across several repositories. The Server component is aggregated from the docs-server, couchbase-cli, backup, and asterix-opt repositories.
A component isn’t recognized by a repository or directory. Instead, the presence of a file named antora.yml indicates that the directories and files nested under it are part of a component.
- Component Descriptor
A component must contain a component descriptor file named antora.yml. When Antora finds antora.yml in a repository, it knows it has located a component (or part of component). The component descriptor tags the files under its hierarchy with the specified component name and version.
In these contributing pages, DOCs issues, and the Antora documentation, the term component-version is used when discussing concepts that apply to a version of a component. It’s important to remember that a component’s name and a component’s version may be very different than the names of the repository and branch where it’s stored.
A module is a discrete bundle of content, including text, images, and other source materials, organized in a hierarchy of folders by content format, then by optional topic if needed. A module is stored in a component’s modules directory. A component can contain one or more modules.
- ROOT Module
The ROOT module contains all the content that’s directly associated with the component itself. When pages in the ROOT module are published, these pages are promoted a level above any other modules' pages in that component’s URL.
The pages directory contains a module’s AsciiDoc files. These files are automatically converted to standalone HTML pages. See the Standard Document Structure to learn how to structure an AsciiDoc file.
The partials directory contains AsciiDoc files that aren’t standalone pages. These files are referenced by an include directive from a document in the pages directory.
Multimedia and supplemental files, organized by format, are stored in the assets directory. Photographs, screenshots, and graphic files in assets/images are inserted into pages using the image macro.