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

Generate local preview

Install ruby

You must have ruby 2.1.0+ installed on your system.

$ ruby -v

If the version is lower than 2.1.0 you must update the version (via brew or using 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

Note: if you encounter an error saying that nokogiri isn't installed follow the steps in this guide to install it on your system.

Generate a local preview.

$ cd md-docs
// to build the 1.3 docs
$ bundle exec jekyll serve --config _config.yml,_config.13.yml --livereload
// or, to build the 1.4 docs
$ bundle exec jekyll serve --config _config.yml,_config.14.yml --livereload
// or, to build the 2.0 docs
$ bundle exec jekyll serve --config _config.yml,_config.20.yml --livereload

Browse the docs at http://localhost:4000/index.html.

The command is using the --livereload flag which will automatically reload the browser window when a change is saved. This only works in Chrome and the LiveReload Chrome Extension must be installed. Once it's installed you should see the small circle filled in gray which indicates that the extension is connected to the Jekyll web server.

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

• Code tabs in markdown
• Table styles
• Pragma marks on REST API doc titles
• Styling blockquotes
• Highlight Objective-C with C

Release notes

Release notes are generated using the GitHubReleaseNotes tool.

1. Download the latest release
2. Unzip and navigate to the folder: cd release-notes-tool
3. 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.

Link checker

To validate links, generate the docs and run the link checker tool.

./build.sh 20
linkchecker tmp/index.html