Repository Organization

    • OUT OF DATE
      +
      This documentation is out of date

      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

      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:

      1. The CLI pages incorporated in the Couchbase Server component.

      2. Standalone man pages that are bundled with the Server software.

      When editing these files, use the man page section structure and formatting.

      Connectors

      The connector repositories use the Gerrit workflow.

      Private Repositories

      Some Couchbase repositories are private. Only Couchbase employees can contribute to the documentation in these components.

      Backup

      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.

      Autonomous Operator

      The Autonomous Operator repository uses the Gerrit workflow and custom branch patterns.

      Analytics

      The Analytics service documentation uses the Gerrit workflow. It is maintained in collaboration with the AsterixDB project.

      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.