= Ribose API
NOTE: Ribose API documentation can be browsed at http://docs.ribose.apiary.io in a human-friendly format. This repository contains source files we build that documentation from, and some build tools. If you are going to contribute to documentation, you are in right place.
== Contributing
=== Setting things up
Clone this repository:
NOTE: The --recursive option initializes and pulls submodules, which are
needed to build the documentation.
See https://git-scm.com/book/en/v2/Git-Tools-Submodules[Git Book] for details.
Install dependencies:
=== Compiling and validating the blueprint
For external reasons, an up-to-date blueprint compilation is required to be
checked into repository. It is stored in apiary.apib file. In order to
compile and validate apiary.apib, run following:
After successful blueprint compilation, a tiny validation tool is run. Issues, if any, will be printed in console.
== Documentation structure
=== Transclusions
We use Hercule tool to compile apiary.apib from the source files. It
introduces the concept of transclusion, which roughly means including one
document in another, at least in our simple case.
To find out more about this tool, visit https://github.com/jamesramsay/hercule.
=== Sections
Final blueprint is built from section subdocuments which reside in the
sections/ directory. The input.apib defines how that document is composed,
hence don't forget to update that file when contributing a new section.
Section subdocuments are transcluded with :()[sections/<section-name>.apib]
expressions. For example, expression :()[sections/space.apib] will transclude
content of sections/space.apib file.
=== Response fixtures
Response fixtures can be imported from spec/fixtures directory
of the https://github.com/riboseinc/ribose-ruby[ribose-ruby] project.
They are transcluded with :()[fixture:fixture-file-name] expression. For
example, :()[fixture:spaces.json] will resolve to spec/fixtures/spaces.json
in ribose-ruby project.
Under the hood, Git submodules are involved. The ribose-ruby project is
added as a submodule in fixtures directory. Run git submodule update to
grab the freshest content, if necessary.
If you want to read more about submodules, Git Book contains an excellent chapter on this topic: https://git-scm.com/book/en/v2/Git-Tools-Submodules
=== Comments
HTML comments can be used in document, either in input.apib or in any section.
They are removed at blueprint compilation.
<!-- This is a HTML comment. -->