Repository Organization
The Couchbase documentation is stored in multiple repositories that are organized in a standard directory structure.
Documentation Repository Roster
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.
Repositories that Require Special Handling
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.
CLI and Backup
The CLI and Backup repositories use the Gerrit workflow and custom branch patterns. Additionally, the AsciiDoc files in these repositories are used to create two sets of documentation: 1. the CLI and Backup pages incorporated in the Couchbase Server component and, 2., standalone man pages that are bundled with the Server software. When editing these files, use the man page section structure and formatting.
Autonomous Operator
The Autonomous Operator repository uses the Gerrit workflow and custom branch patterns. The documentation is stored in docs/user.
Analytics
The Analytics service documentation is maintained in collaboration with the AsterixDB project. See its README for contributing instructions.
Directory Structure and Key Files
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.
- Component
-
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.
- Component-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.
- Module
-
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.
- Pages
-
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.
- Partials
-
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.
- Assets
-
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.
- Examples
-
Non-AsciiDoc files, such as source code, are stored in the examples directory. These files are often inserted into code blocks using an include directive.
- Navigation
-
A navigation file, often named nav.adoc, contains one or more AsciiDoc lists. Antora uses these files to build the site’s component navigation menus.