Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://bshaffer.github.io/oauth2-server-php-docs/

documentation for the oauth2-server-php library
https://bshaffer.github.io/oauth2-server-php-docs/

Last synced: about 1 month ago
JSON representation

documentation for the oauth2-server-php library

Awesome Lists containing this project

README 

        
# OAuth2 Server PHP Documentation



This repository hosts the [documentation](http://bshaffer.github.io/oauth2-server-php-docs/) for the

[oauth2-server-php](https://github.com/bshaffer/oauth2-server-php) library.



All submissions are welcome! To submit a change, fork this repo and send us a [pull request](http://help.github.com/send-pull-requests/).



## Setup



Ruby 1.9 is required to build the site.



Get the nanoc gem, plus kramdown for markdown parsing:



    bundle install



Compile the src into the `output` directory by running the following command:



    nanoc compile



You can see the available commands with nanoc:



    nanoc -h



Nanoc has [some nice documentation](http://nanoc.stoneship.org/docs/3-getting-started/) to get you started.  Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.



## Development



Nanoc compiles the site into static files living in `./output`.  It's

smart enough not to try to compile unchanged files:



    $ nanoc compile

    Loading site data...

    Compiling site...

       identical  [0.00s]  output/css/960.css

       identical  [0.00s]  output/css/pygments.css

       identical  [0.00s]  output/css/reset.css

       identical  [0.00s]  output/css/styles.css

       identical  [0.00s]  output/css/uv_active4d.css

          update  [0.28s]  output/index.html



    Site compiled in 5.81s.



You can setup whatever you want to view the files.  If you have the adsf

gem, however (I hope so, it was in the Gemfile), you can start Webrick:



    $ nanoc view

    $ open http://localhost:3000



Compilation times got you down?  Use `autocompile`!



    $ nanoc autocompile



This starts a web server too, so there's no need to run `nanoc view`.

One thing: remember to add trailing slashes to all nanoc links!



## Deploy



    $ rake publish



## Styleguide



Not sure how to structure the docs?  Here's what the structure of the

API docs should look like:



    # API title



    ## API endpoint title



        [VERB] /path/to/endpoint.json



    ### Parameters



    name

    : description



    ### Input (request json body)



    <%= json :field => "sample value" %>



    ### Response



    <%= headers 200, :pagination => true, 'X-Custom-Header' => "value" %>

    <%= json :resource_name %>



**Note**: We're using [Kramdown Markdown extensions](http://kramdown.rubyforge.org/syntax.html), such as definition lists.



### JSON Responses



We specify the JSON responses in ruby so that we don't have to write

them by hand all over the docs.  You can render the JSON for a resource

like this:



```erb

<%= json :issue %>

```



This looks up `GitHub::Resources::ISSUE` in `lib/resources.rb`.



Some actions return arrays.  You can modify the JSON by passing a block:



```erb

<%= json(:issue) { |hash| [hash] } %>

```



### Terminal blocks



You can specify terminal blocks with `pre.terminal` elements.  It'd be

nice if Markdown could do this more cleanly...



    

    $ curl foobar

    ....

    



This isn't a `curl` tutorial though, I'm not sure every API call needs

to show how to access it with `curl`.