diff --git a/docs/_config.y0ml b/docs.old/_config.y0ml similarity index 100% rename from docs/_config.y0ml rename to docs.old/_config.y0ml diff --git a/docs/index.md b/docs.old/index.md similarity index 100% rename from docs/index.md rename to docs.old/index.md diff --git a/docs/reviewing.md b/docs.old/reviewing.md similarity index 100% rename from docs/reviewing.md rename to docs.old/reviewing.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100755 index 0000000..0a3bcf2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,8 @@ +.* +!.gitignore +!.gitmodules +*~ + +components/ + +_site/ diff --git a/docs/LICENSE.md b/docs/LICENSE.md new file mode 100644 index 0000000..38c6bf2 --- /dev/null +++ b/docs/LICENSE.md @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) [year] [fullname] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..41d7da5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,22 @@ +SRC = $(wildcard lib/*/*.js) +HTML = $(wildcard lib/*/*.html) +TEMPLATES = $(HTML:.html=.js) +LESS = $(wildcard lib/*/*.less) +CSS = $(LESS:.less=.css) + +build: components $(SRC) $(TEMPLATES) $(CSS) + @component build --verbose --out . --name assets + +components: component.json + @component install + +%.js: %.html + @component convert $< + +%.css: %.less + @lessc $< $@ + +clean: + rm -fr build components $(TEMPLATES) + +.PHONY: clean diff --git a/docs/README.md b/docs/README.md new file mode 100755 index 0000000..3d8432b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,68 @@ +## The "What ?" and the "Why ?" + +**Carte** is a simple Jekyll based documentation website for APIs. It is designed as a boilerplate to build your own documentation and is heavily inspired from [Swagger](http://swagger.wordnik.com/) and [I/O docs](http://www.mashery.com/product/io-docs). Fork it, add specifications for your APIs calls and customize the theme. Go ahead, see if we care. + +We built **Carte** because the existing options (Swagger and the likes) were trying to do too much and did not match our needs: + +1. Most of our API calls are sending JSON objects, as opposed to a series of parameters, +1. Being able to query the real API is nice, but running anything but `GET` calls can get tricky ("What do you mean I deleted my stuff? I was just trying out the API calls!"), +1. Overall, setting up a separate server for what really requires a good static documentation seemed overkill. + +The real value of **Carte** is its structure for describing APIs, not its underlying technical stack (or lack-thereof). In a nutshell; **we built a static template for your API documentation, feel free to re-use it**. + +## Install + +It' Jekyll god dammit: + +1. Clone this repository on your local, +1. [Install Jekyll](https://github.com/mojombo/jekyll/wiki/install), +1. Go at the root of the repository and run ```jekyll serve --watch```, +1. Go to http://localhost:4000, +1. [Great success! High five!](http://www.youtube.com/watch?v=wWWyJwHQ-4E) + +## How to... + +### Adding a new API call + +You can add a new API call by simply adding a new post in the `_posts` folder. Jekyll by default forces you to specify a date in the file path: it makes us sad pandas too, but you'll have to stick to this format. You can use dates to control the order in which API calls are displayed in the interface. + +Each API call can define a few values in its YAML header: + +Variable | Mandatory | Default | Description +--- | --- | --- | --- +``title`` | Y | - | A short description of what that calls does. +``path`` | N | - | The URL for the API call, including potential parameters. +``type`` | N | - | Set it to `PUT`, `GET`, `POST`, `DELETE` or nothing (for parts of your documentation that do not relate to an actual API call). + +A typical header: + +``` +--- +path: '/stuff/:id' +title: 'Delete a thing' +type: 'DELETE' + +layout: nil +--- +``` + +We then describe the request and response (or whatever else you wish to talk about) in the body of our post. Check the placeholders present in the `_posts` folder to get an idea of what it can look like. + +### Grouping calls + +Adding a category to your YAML header will allows you to group methods in the navigation. It is particularly helpful as you start having a lot of methods and need to organize them. For example: + +``` +--- +category: Stuff +path: '/stuff/:id' +title: 'Delete a thing' +type: 'DELETE' + +layout: nil +--- +``` + +### Edit the design + +The default UI is mostly described through the `css/style.css` file and a couple short jQuery scripts in the `/_layouts/default.html` layout. Hack it to oblivion. diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100755 index 0000000..bf981dd --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,6 @@ +--- +exclude: ['README.markdown'] +permalink: ':title' +pygments: true +safe: false +title: 'Carte' \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100755 index 0000000..4e637e1 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,17 @@ + +
+