monolithe 1.0.0

Monolithe is a sdk generator

# Monolithe

Monolithe is a Python toolset that generates sdks with their documentation and ReST api documentation based some specifications and configuration.

It provides the following commands:

- `monogen-sdk`: generates a bambou-based sdk according to specifications and configuration.
- `monogen-apidoc`: generates ReST api documentation according to specifications and configuration.

The specifications are a set of files containing json data describing one object per file, its properties and their characteristics, and its position in the api hierarchy.

> For more info, please read the [Monolithe Specifications Reference](Specifications Reference.md).

In addition to the specifications, Monolithe uses a configuration that describes all the information relative to your sdk. For instance, you can set its name, the class prefix, some vanilla files, the license, and so on.

> For more info, please read the [Monolithe Configuration & Vanilla Reference](Configuration & Vanilla Reference.md).

Monolithe is before all a framework that you can integrate with other tools.

> For more info, please read the Monolithe API Documentation (TODO).


## Installation

> And remember, kids! You should always be using a virtualenv.

You can install Monolithe from PyPi:

$ pip install monolithe

Or install it from the source:

$ python setup.py install

Or install it in develop mode:

$ python setup.py develop

Or directly run the command wrappers provided in the `commands` directory. Simply install the dependencies once:

$ pip install -r requirements.txt


## ToDoList Tutorial

You can find an `examples` folder in the source code repository. This contains a working example for a todo list api.
More informations can be found in each files of the examples.

> Be sure to have Flask installed in addition to Monolithe's `requirements.txt`.

The example is composed of:

- Some specifications in `examples/specifications/`
- A Monolithe configuration in `examples/conf/conf.ini`
- Some vanilla data in `examples/vanilla`
- A `demo-server.py` command that starts a really stupid server that implements a ReST API for the ToDoList
- A `demo-client.py` command that interacts with the server using the generated sdk named `tdldk`.

### Step 1: install dependencies

$ cd monolithe # be sure to go and stay there for the rest of the tutorial ;)
$ pip install flask
$ pip install -r `requirements.txt`


### Step 2: generate the tdldk

$ ./commands/monogen-sdk --config examples/conf/conf.ini --folder examples/specifications

> Customizable using the configuration and the content of the `vanilla/sdk` folder.

> You can also generate the sdk documentation by adding the `--doc` argument. But it's slow.

You'll see a `codegen` directory created under `examples`.

It contains all the auto-generated sdk source code according to the specifications files.

You can install it by doing:

$ cd examples/codegen
$ python setup.py develop
$ cd ../..

> This is mandatory for Step 6

> Don't forget to come back to the root folder

### Step 3: generate the ReST api documentation

$ ./commands/monogen-apidoc --config examples/conf/conf.ini --folder examples/specifications

> Customizable using the configuration and the content of the `vanilla/apidoc` folder.

You'll see a `apidocgen` directory created under `examples`.

You can open the `index.html` to navigate the api documentation.


### Step 4: start the demo server

$ ./examples/demo-server.py
> * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
> * Restarting with stat

check that it's working by doing

$ curl http://127.0.0.1:5000/api/v1_0/lists
> [{"description": "Things to buy", "ID": "1", "title": "Shopping List"}, {"description": "You should not see this", "ID": "2", "title": "Secret List"}]


### Step 5: run the client

$ ./examples/demo-client.py

And follow on screen instructions.

> For mor information, open the `demo-client.py` file and follow the comments.


### Step 6: have fun with the cli

Each Monolithe SDK comes with a command line interface. According to the Monolithe Configuration file, this cli is named `tdl`.

You can simply run

# hint: the exports can be put in a source file ;)
$ export TDL_USERNAME=user
$ export TDL_PASSWORD=password
$ export TDL_API_URL=http://127.0.0.1:5000
$ export TDL_API_VERSION=1.0
$ export TDL_ENTERPRISE=root

$ tdl create task --in lists 2 -p title='my task' description='from cli'
> [Success] task has been created with ID=b3ae22d2-6c87-11e5-be61-080027ba8f35
> +--------------+--------------------------------------+
> | status | TODO |
> | description | from cli |
> | title | my task |
> | parentType | <the demo server doesn't handle that>|
> | parentID | 2 |
> | owner | <the demo server doesn't handle that>|
> | creationDate | <the demo server doesn't handle that>|
> | ID | b3ae22d2-6c87-11e5-be61-080027ba8f35 |
> +--------------+--------------------------------------+

$ tdl list tasks --in lists 2
> [Success] 3 tasks have been retrieved
> +----------+---------------------------+---------------------+--------------+------------+---------+----------------+------+
> | status | description | title | parentType | parentID | owner | creationDate | ID |
> |----------+---------------------------+---------------------+--------------+------------+---------+----------------+------|
> | TODO | We are doing it right now | Explain Monolithe | list | 2 | | | 21 |
> | TODO | Almost done | Make Garuda popular | list | 2 | | | 22 |
> | TODO | That is the plan | Dominate the world | list | 2 | | | 23 |
> | TODO | from cli | my task | | 2 | | |[snip]|
> +----------+---------------------------+---------------------+--------------+------------+---------+----------------+------+

> `tdl --help` for the complete usage

## Command Line Interfaces Quick Reference

### monogen-sdk
This command will generate a sdk using specifications either from a local folder, or from a Github repository.

#### From Github

Using your username/password:

$ monogen-sdk --config [conf.ini] --branches [branch1[,branch2,...branchX]]
> Enter your Github API URL: [https://api.github.com/v3]
> Enter your Github login: [username]
> Enter your Github organization: [repo-organization]
> Enter your Github repository: [repo-name]
> Enter your Github password for amercada: [password]

Of course, you can give all those parameters right from the cli:

$ monogen-sdk --config [conf.ini] -g [https://api.gitbhub.com/3] -l [username] -o [repo-organization] -r [repo-name] -b [branch1[,branch2,...branchX]]
> Enter your Github Password:

You can also use a Github Application Token (https://github.com/settings/tokens):

$ monogen-sdk --config [conf.ini] -g [https://gitbhub.com] -t [token] -o [repo-organization] -r [repo-name] -b [branch1[,branch2,...branchX]]

Then you won't have to enter your password.

You can also defaults certains arguments by using a environment variables, and eventually put them in a source file:

$ cat ~/.monorc
> export MONOLITHE_GITHUB_API_URL=[https://api.github.com/v3]
> export MONOLITHE_GITHUB_TOKEN=[token]
> export MONOLITHE_GITHUB_ORGANIZATION=[repo-organization]
> export MONOLITHE_GITHUB_REPOSITORY=[repo-name]
> export MONOLITHE_CONFIG_REPOSITORY_PATH=[/path/to/specsfolder]
> export MONOLITHE_CONFIG_FULLPATH=[path/to/conf]
$ source ~/.monorc

Then simply:

$ monogen-sdk -b [branch1[,branch2,...branchX]]


##### From a folder

$ monogen-sdk --config [conf.ini] --folder [/path/to/specifications/]



#### monogen-apidoc

This command will generate a ReST api documentation using specifications either from a local folder, or from a Github repository.

> This command is very similar to `monogen-sdk`.

##### From a folder

$ monogen-apidoc --config [conf.ini] --folder [/path/to/specifications/]

##### From Github

The `monogen-apidoc` works exactly the same than `monogen-sdk`