Balanced Docs

This project builds the following Balanced documentation:

• Specification
• Reference
• Overview

Contributing

All contributions, even simple grammar fixes, are greatly appreciated.

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
2. Fork the repository on Github to start making your changes to the develop branch (or branch off of it).
3. Send a pull request!

Make sure to add yourself to CONTRIBUTORS. We will showcase the CONTRIBUTORS file on our COMMUNITY PAGE.

After your pull request, email support [@] balancedpayments.com with your address and the link to your pull request with your address and your t-shirt size so we can send you your very own Balanced t-shirt!

Setup

You'll first need:

• python 2.7+
• virtualenvwrapper
• bower

And then you can setup your environment like this:

git clone git@github.com:balanced/balanced-docs.git
cd balanced-docs
git submodule update --init --recursive --remote
mkvirtualenv balanced-docs
python setup.py develop
pip install -r requirements.txt

If you've done that before just do:

cd /path/to/balanced-docs
workon balanced-docs
git submodule update --init --recursive --remote

Build

Now that your environment is setup, let's build the documentation. To build them all at once do:

make all

Specification

To build the specification do:

make spec

Overview

To build the overview do:

make overview

Reference

To build the reference do:

make api

Preview

Let's take a look at what we've built using mongoose:

cd build
mongoose
// Mongoose web server v. 3.8 started on port(s) 8080 with web root [.]

Specification

Open up http://localhost:8080/spec

Overview

Open up http://localhost:8080/overview.shtml

Reference

Open up http://localhost:8080/api.shtml

Hacking

rST

All of the documentation is written in r(e)S(tructured)T(ext) which you can read about here.

dcode

We've added a custom rST directive called dcode which uses external scripts to generate rST content. For example:

.. dcode:: scenario credit_create_new_bank_account

Here we are asking dcode to run the credit_create_new_bank_account. The output for that scenario will end up in place of the directive.

You'll also see a corresponding dcode-default directive. For example:

.. dcode-default:: scenario
    :script: ../scenario.py -d ../scenarios -c scenario.cache
    :section-chars: ~^
    :lang: ruby

Which registers an external script for scenario. As a result the dcode directive above will result in this call:

../scenario.py -d ../scenarios -c scenario.cache credit_create_new_bank_account --lang ruby

Run individual scenario

scripts/lang-scenario.py -d clients/{REVISION}/curl hold_create

Edit field descriptions for scenarios

Field descriptions are from balanced.rev1.json, which are generated from balanced-api. The "forms" used in balanced-docs are assembled from parameters supplied in the scenarios in balanced-api. Those scenarios should be updated to include the fields missing the specific scenario section and a newly generated balanced.rev1.json be committed into the docs. To generate balanced.rev1.json in balanced-api run:

bundle exec rake features:all

DO NOT run

bundle exec rake parallel:features

doing so causes the file to overwrite itself.