The schemas are documents (text files) that formally describe the messages that pass between GA4GH servers and clients, which we also refer to collectively as "the API." The schemas are written in a language called Protocol Buffers 3.
For instructions on how to install Protocol Buffers 3 on your system, consult the protocol buffers C++ installation instructions page.
We use the schemas in a couple of different ways:
- to generate source code
- to generate documentation
$ cd src/main/proto && protoc --python_out=. ga4gh/*
We use a tool called Sphinx to generate the documentation from Protocol Buffers input files.
To use the Sphinx/Protocol Buffers documentation generator, you must install some software packages it requires.
We use the Maven build tool to control processing the schemas. Installing Maven will also install Java.
$ sudo apt-get install maven
$ sudo yum install maven
$ brew install maven
We use some Python utility programs also.
Install the Python installer pip.
$ sudo apt-get install python-pip
$ sudo yum install python-pip
Use brew:
$ brew install pip
Or download pip from here
and run it:
$ python get-pip.py
Do this once to install all required Python packages:
$ sudo pip install -r python/dev-requirements.txt -c python/constraints.txt
With those prerequisites out of the way, do this anytime you wish to generate the documentation.
Assuming your working directory is the base "schemas" directory,
do this:
$ mvn site
The documentation you generate will reside in
target/generated-docs/merged/html. To view it, open the file
target/generated-docs/merged/html/index.html in a browser.