Merge pull request oauthjs#369 from maxtruxa/v3-docs

Add documentation

Author: mjsalinger

.gitignore

@@ -1 +1,5 @@
-node_modules
+node_modules/
+docs/_build/
+__pycache__/
+*.pyc
+

README.md

@@ -1,99 +1,75 @@
-Complete, compliant and well tested module for implementing an OAuth2 server in [node.js](https://nodejs.org/).
+# oauth2-server
 
-  [![NPM Version][npm-image]][npm-url]
-  [![Build Status][travis-image]][travis-url]
-  [![NPM Downloads][downloads-image]][downloads-url]
+[![npm Version][npm-image]][npm-url]
+[![npm Downloads][downloads-image]][downloads-url]
+[![Test Status][travis-image]][travis-url]
+[![MIT Licensed][license-image]][license-url]
+[![oauthjs Slack][slack-image]][slack-url]
 
-# Quick Start
+Complete, compliant and well tested module for implementing an OAuth2 server in [Node.js](https://nodejs.org).
 
-  The _node-oauth2-server_ module is framework-agnostic but there are several wrappers available for popular frameworks such as [express](https://github.com/oauthjs/express-oauth-server) and [koa 2](https://github.com/oauthjs/koa-oauth-server).
 
-  Using the _express_ wrapper (_recommended_):
+## Installation
 
-```js
-var express = require('express');
-var oauthServer = require('express-oauth-server');
-var app = express();
+```bash
+npm install oauth2-server
+```
 
-var oauth = new oauthServer({ model: model });
+The *oauth2-server* module is framework-agnostic but there are several officially supported wrappers available for popular HTTP server frameworks such as [Express](https://npmjs.org/package/express-oauth-server) and [Koa](https://npmjs.org/package/koa-oauth-server). If you're using one of those frameworks it is strongly recommended to use the respective wrapper module instead of rolling your own.
 
-app.use(oauth.authenticate());
 
-app.get('/', function (req, res) {
-  res.send('Hello World');
-})
+## Features
 
-app.listen(3000);
-```
+- Supports `authorization_code`, `client_credentials`, `refresh_token` and `password` grant, as well as *extension grants*, with scopes.
+- Can be used with *promises*, *Node-style callbacks*, *ES6 generators* and *async*/*await* (using [Babel](https://babeljs.io)).
+- Fully [RFC 6749](https://tools.ietf.org/html/rfc6749.html) and [RFC 6750](https://tools.ietf.org/html/rfc6749.html) compliant.
+- Implicitly supports any form of storage, e.g. *PostgreSQL*, *MySQL*, *MongoDB*, *Redis*, etc.
+- Complete [test suite](https://github.com/oauthjs/node-oauth2-server/tree/master/test).
 
-  Using this module directly (_for custom servers only_):
 
-```js
-var Request = require('oauth2-server').Request;
-var oauthServer = require('oauth2-server');
+## Documentation
 
-var oauth = new oauthServer({ model: model });
+[Documentation](https://oauth2-server.readthedocs.io) is hosted on Read the Docs.
 
-var request = new Request({
-  headers: { authorization: 'Bearer foobar' }
-});
 
-oauth.authenticate(request)
-  .then(function(data) {
-    // Request is authorized.
-  })
-  .catch(function(e) {
-    // Request is not authorized.
-  });
-```
+## Examples
 
-  _Note: see the documentation for the [specification][wiki-model-specification] of what's required from the model._
+Most users should refer to our [Express](https://github.com/oauthjs/express-oauth-server/tree/master/examples) or [Koa](https://github.com/oauthjs/koa-oauth-server/tree/master/examples) examples.
 
-# Features
+Examples for v3 are yet to be made. Examples for v2 can still be found [here](https://github.com/oauthjs/node-oauth2-server/tree/b36a06b445ad0a676e6175d68a8bd0b2f3353dbf/examples).
 
-  - Supports `authorization_code` (with scopes), `client_credentials`, `password`, `refresh_token` and custom `extension` grant types.
-  - Can be used with _node-style_ callbacks, promises and ES6 _async_/_await_.
-  - Fully [RFC6749](https://tools.ietf.org/html/rfc6749) and [RFC6750](https://tools.ietf.org/html/rfc6750) compliant.
-  - Implicitly supports any form of storage e.g. _PostgreSQL_, _MySQL_, _Mongo_, _Redis_, _etc_.
-  - Full test suite.
+[//]: # (If you're implementing a custom server, we have many examples available:)
 
-# Documentation
+[//]: # (- A simple **password** grant [example](https://github.com/oauthjs/node-oauth2-server/tree/master/examples/password).)
+[//]: # (- A more complex **password** and **refresh_token** grant [example](https://github.com/oauthjs/node-oauth2-server/tree/master/examples/refresh-token).)
+[//]: # (- An advanced **password**, **refresh_token** and **authorization_code** grant [example](https://github.com/oauthjs/node-oauth2-server/tree/master/examples/authorization-code) with scopes.)
 
-  - [Server options][wiki-server-options]
-  - [Model specification][wiki-model-specification]
-    - [Authorization Code][wiki-model-specification]
-    - [Client Credentials][wiki-model-specification]
-    - [Password][wiki-model-specification]
-    - [Refresh token][wiki-model-specification]
-    - [Custom extension][wiki-model-specification]
 
-# Examples
+## Upgrading from 2.x
 
-  Most users should refer to our [express](https://github.com/seegno/express-oauth-server/tree/master/examples) or [koa](https://github.com/thomseddon/koa-oauth-server/tree/master/examples) examples. If you're implementing a custom server, we have many examples available:
+This module has been rewritten using a promise-based approach, introducing changes to the API and model specification.
 
-  - A simple **password** grant authorization [example](examples/password).
-  - A more complex **password** and **refresh_token** [example](examples/refresh-token).
-  - An advanced **password**, **refresh_token** and **authorization_code** (with scopes) [example](examples/authorization-code).
+Please refer to our [3.0 migration guide](https://github.com/oauthjs/node-oauth2-server/wiki/Migrating-from-2-x-to-3-x) for more information.
 
-# Upgrading from 2.x
 
-  This module has been rewritten with a promise-based approach and introduced a few changes in the model specification.
+## Tests
 
-  Please refer to our [3.0 migration guide][wiki-migrating-from-2x-to-3x] for more information.
+To run the test suite, install dependencies, then run `npm test`:
 
-## License
+```bash
+npm install
+npm test
+```
 
-  [MIT](LICENSE)
 
-<!--- badge links -->
 [npm-image]: https://img.shields.io/npm/v/oauth2-server.svg
 [npm-url]: https://npmjs.org/package/oauth2-server
-[travis-image]: https://img.shields.io/travis/oauthjs/node-oauth2-server/master.svg
-[travis-url]: https://travis-ci.org/oauthjs/node-oauth2-server
 [downloads-image]: https://img.shields.io/npm/dm/oauth2-server.svg
 [downloads-url]: https://npmjs.org/package/oauth2-server
+[travis-image]: https://img.shields.io/travis/oauthjs/node-oauth2-server/master.svg
+[travis-url]: https://travis-ci.org/oauthjs/node-oauth2-server
+[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
+[license-url]: https://raw.githubusercontent.com/oauthjs/node-oauth2-server/master/LICENSE
+[slack-image]: https://img.shields.io/badge/slack-join-E01563.svg
+[slack-url]: https://oauthjs.slack.com
 
-<!--- wiki links -->
-[wiki-model-specification]: https://github.com/oauthjs/node-oauth2-server/wiki/Model-specification
-[wiki-migrating-from-2x-to-3x]: https://github.com/oauthjs/node-oauth2-server/wiki/Migrating-from-2-x-to-3-x
-[wiki-server-options]: https://github.com/oauthjs/node-oauth2-server/wiki/Server-options

docs/Makefile

@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/oauth2-server.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/oauth2-server.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/oauth2-server"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/oauth2-server"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/_static/custom.css

@@ -0,0 +1,68 @@
+
+/* fix word-wrap for responsive tables, as described here:
+ * http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */
+@media screen and (min-width: 767px) {
+  .wy-table-responsive table td {
+    white-space: normal !important;
+  }
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
+}
+
+/* ensure that smaller tables span the whole page width */
+.rst-content table.docutils {
+  width: 100% !important;
+}
+
+/* "Name" column of "arguments" tables */
+.rst-content table.docutils th:nth-child(1),
+.rst-content table.docutils td:nth-child(1) {
+  width: 35% !important;
+  word-break: break-all !important;
+}
+
+/* "Type" column of "arguments" tables */
+.rst-content table.docutils th:nth-child(2),
+.rst-content table.docutils td:nth-child(2) {
+  width: 20% !important;
+  word-break: normal !important;
+}
+
+/* "Description" column of "arguments" tables */
+/*.rst-content table.docutils th:nth-child(3),
+.rst-content table.docutils td:nth-child(3) {
+}*/
+
+/* use a slightly smaller font size for table contents */
+.rst-content table.docutils th,
+.rst-content table.docutils td {
+  font-size: 85% !important;
+}
+
+/* reduce left/right padding of literals from 5px to 3px */
+.rst-content code.literal {
+  padding-left: 3px !important;
+  padding-right: 3px !important;
+}
+
+/* reset font-size of literals inside the term definition (<dt>) in description lists */
+.rst-content dl dt code.literal {
+  font-size: 100% !important;
+}
+
+/* external links generated by the :rfc: role are surrounded by
+ * <strong> tags which doesn't look good in floating text */
+.rst-content a.rfc strong {
+  font-weight: normal !important;
+}
+
+/* default style for blockquotes is just indentation;
+ * disable indentation and instead use custom background color */
+.rst-content blockquote {
+  margin-left: 0 !important;
+  padding: 10px !important;
+  background-color: #fff8dc !important;
+  border-left: 2px solid #ffeb8e !important;
+}
+