Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Balanced's API Documentation
CSS Python Shell Other

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
api
assets
balanced_docs
clients/rev1
overview/rev1
scripts
spec
.bowerrc
.gitignore
.gitmodules
.travis.yml
CONTRIBUTORS
Makefile
README.md
balanced.json
balanced.rev1.json
bower.json
custom_htmltranslations.py
package.json
requirements.txt
scenario.cache
setup.py

README.md

Balanced Docs

Build Status

This project builds the following Balanced documentation:

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:

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.

Something went wrong with that request. Please try again.