Sync Gateway Documentation

This repository hosts the documentation source for Couchbase’s Sync Gateway product.

Contributing

Couchbase recognizes and values the experience and skills of the wider Couchbase community. As such, open source contributions to our documentation are always welcome.

If you find an error, or see room for improvement on a page, please don’t keep it to yourself. Even if you don’t plan to make the change yourself, we would still like to know what it is!

Raise a DOC issue by clicking the Leave Additional Feedback? link on the bottom-right of any page on this site.
You can also submit simple changes, such as typo fixes and minor clarifications or more extensive content additions and updates — see Contributing Workflow.

Check out our contributing guide to learn more on how to:

Submit a bug or feedback issue
Set up your documentation workspace
build the documentation
submit a pull request

Thank you for helping to make the documentation better.

All bugs and enhancements for the Couchbase documentation are tracked using the DOC project issue board.

Docs Component Configuration

This repository contains an Antora docs component. Keep in mind these key repository features:

Component name, version, and start page are configured in each branch’s antora.yml file.
The navigation for Sync Gateway is stored in the ROOT module’s nav.adoc file.
Production branches use the release/X.Y naming pattern (e.g., release/2.8, release/3.0).
- The docs site playbook instructs Antora to automatically aggregate any branch names that start with release/.

Documentation Site Toolchain

The documentation source files are marked up with AsciiDoc. 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.

The docs components and site UI are orchestrated by the docs site playbook as described in the contributing guide.

Significant Files

_partials Files

_set_page_context.adoc
The contents of the modules/ROOT/pages/_partials/_set_page_context.adoc file are used to set-up the environment for each page.

This file in turn calls _define_page_index.adoc and _define_component_attributes.adoc.

Together, these included files define a tailored, platform-specific environment, whilst utilizing common text files to describe Couchbase Lite functionality.
_define_component_attributes.adoc
The modules/ROOT/pages/_partials/_attributes_local.adoc file sets the value of attributes.
_define_page_index.adoc
This file sets the page xref attributes used in cross-references throughout the documentation. It picks-up the platform parameters from the _set_page_context.adoc
block-related-content-<topic>.adoc
These files are/may be used to present the appropriate releated content links at the foot of each page.
blocklinks-cbl.adoc
Presents a standard parameterized block of links into the array of Couchbase Lite platform modules.
pn-issues-list.adoc
This file is used to hold all issues, known errors etc for this 'major' release. Its contents are included in the release notes.
stats-scheme-<group>.adoc
Provide xref links into the stats schema. Included by stats-monitoring.adoc.
topic-group-<topic>.adoc
Use to present a standardized related links section at the head of 'most' pages.
The static_restapi folder
The content of this folder are generated using Swagger2Markup to process the various API yaml files and produce browseable API content.

Generate the docs by using a terminal to run mvn generate-sources from within the assets/s2adoc folder.

Assets Files

assets/s2adoc folder
The contents of this folder provide Swagger2Markup configuration to generate static pages for the API content; these supplement the SwaggerUI pages.

Generate the docs by using a terminal to run mvn generate-sources from within this folder.

Configuration is defined in the pom.xml file.
assets/attachments/rest-api-admin.yaml
The contents of this file describe the ADMIN REST API.
They are used by both Swagger2Markup and SwaggerUI to generate static and dynamic API pages respectively.
assets/attachments/rest-api-public.yaml
The contents of this file describe the PUBLIC REST API. They are used by both Swagger2Markup and SwaggerUI to generate static and dynamic API pages respectively.
assets/attachments/rest-api-metrics.yaml
The contents of this file describe the METRICS REST API. They are used by both Swagger2Markup and SwaggerUI to generate static and dynamic API pages respectively.
assets/attachments/SG_<object>_model.adoc files
The contents of these files describe the data properties of selected API elements. They are generated from the rest-api-admin.yaml file and are used to provide content in the configuration-schema-<object>.adoc pages.

Page Structure

Within the ROOT/PAGES folder, each page calls

_set_page_context.adoc, which in turn:
1. Sets any required module-level (ROOT) parameters
2. Invokes _define_component_attributes.adoc to set common attributes
3. Invokes _define_page_index.adoc to set up xref attribute for page cross-references
4. Invokes _define_glossary_links.adoc to set up xref attributes for the glossary
Invokes _show_page_header_block.adoc to render the standard page header, abstract etc
Renders the required content
Includes a common footer file, for example block-related-content-api.adoc

1cedsoda / docs-sync-gateway