couchbase / docs-sync-gateway

Documentation for Sync Gateway -

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

1. _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

2. Invokes _show_page_header_block.adoc to render the standard page header, abstract etc

3. Renders the required content

4. Includes a common footer file, for example block-related-content-api.adoc