Couchbase Mobile Developer Portal

Contributing to Docs

To update documentation, find the page that you wish to change on developer.couchbase.com and click the Edit on GitHub button to open the backing markdown file.

Note: If the page you want to edit doesn't have the Edit on GitHub button it means that it hasn't been migrated to this contribution process yet. In this case, you can file a new issue.

From there you can click the Edit button to write changes on GitHub. Make sure to check the Style Guide in the next section to get familiar with the writing rules.

Once you are done with edits scroll to the bottom of the page and select the create new branch option.

Then click the Propose file change button which will open a PR with the changes. Someone with push access to the master branch will then review the changes and merge the PR.

Style Guide

Markdown Style Guide

Other Notes (optional)

Clone the git repository

Use Git to clone the Couchbase Mobile Portal repository to your local disk:

git clone git@github.com:couchbaselabs/couchbase-mobile-portal.git
cd couchbase-mobile-portal
git submodule init && git submodule update

Generate local preview

Install ruby from brew (or use rvm):

$ brew install ruby

and then open a new terminal to refresh the environment.

Install Jekyll and the local dependencies.

$ cd md-docs
$ gem install bundler
$ bundle install

Generate a local preview.

$ cd md-docs
$ bundle exec jekyll serve --config _config.yml,_config.13.yml
// or
$ bundle exec jekyll serve --config _config.yml,_config.14.yml
// or
$ bundle exec jekyll serve --config _config.yml,_config.20.yml

Writing guide

To contribute to Guides, API references or REST APIs, read the following. You don't need to build the site locally. Just find the content that needs editing and submit a pull request.

Code tabs

To add code tabs in your markdown file add the following html tag:

<div class="tabs"></div>

Then use code fencing with the + character to specify that its part of code tabs.

Objective-C  -> ```objective-c+
Swift        -> ```swift+
Java         -> ```java+
C#           -> ```c+

GitHub will render 4 code blocks one after the other but don't worry, the tabs will be displayed as expected on the site.

REST API

REST APIs are documented using Swagger. Read more in the readme of the swagger folder.

API References

API references are documented in https://github.com/couchbaselabs/couchbase-lite-api.

Ingestion hacks

Release notes

Release notes are generated using the GitHubReleaseNotes tool.

Download the latest release
Unzip and navigate to the folder: cd release-notes-tool
Generate the release notes in Couchbase Mobile's custom XML format: mono bin/Debug/ReleaseNotesCompiler.CLI.exe update --owner couchbase --repository couchbase-lite-ios --targetcommitish master -u USER -p PASS -m 1.3 --exportxml

Repositories to generate release notes for:

couchbase-lite-net
couchbase-lite-ios
couchbase-lite-java-core
couchbase-lite-java
couchbase-lite-android
sync_gateway

The tool outputs the XML for each repository in the current directory.

For SG, copy the article to docs/src/guides/sync-gateway/release-notes.xml.
For CBL, copy the topic to docs/src/guides/couchbase-lite/release-notes.xml.

CMS release tags

Create a new key-value pair for the new version (on cms-qa for example).
Create a new documentation set for the new version (on cms-qa for example)
Make the latest documentation set the current one and uncheck the previous one if necessary.

PaulMilla/couchbase-mobile-portal