Merge pull request #122 from chenjr0719/docs

Docs

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.6.0 (2019-08-02)
+
+### Features
+
+* Add API module ([4a43817](https://github.com/huge-success/sanic-openapi/pull/111))
+* Make it possible to register the same model definition multiple times in `doc.definitions` ([3c3329c](https://github.com/huge-success/sanic-openapi/pull/110))
+* Support Swagger configuration ([a093d55](https://github.com/huge-success/sanic-openapi/pull/100))
+* Super call added to List field serialize method ([93ab6fa](https://github.com/huge-success/sanic-openapi/pull/93))
+* Support and examples for Class-Based Views (HTTPMethodView) ([de21965](https://github.com/huge-success/sanic-openapi/pull/64))
+* Add operation decorator ([039a0db](https://github.com/huge-success/sanic-openapi/pull/95))
+* Add a if-statement at build_spec checking add default 200 response or not ([1d8d7d0](https://github.com/huge-success/sanic-openapi/pull/116))
+* Add File field & Fix some line with black style ([06c662b](https://github.com/huge-success/sanic-openapi/pull/120))
+
+### Bug Fixes
+
+* Allow empty list with List field ([74fd710](https://github.com/chenjr0719/sanic-openapi/commit/74fd710))
+* fix example of class based view ([9c0bbd3](https://github.com/chenjr0719/sanic-openapi/commit/9c0bbd3))
+* Ignore routes under swagger blueprint ([ed932cc](https://github.com/chenjr0719/sanic-openapi/commit/ed932cc))
+* fix static and exclude ([5a8aab8](https://github.com/huge-success/sanic-openapi/pull/80))
+
+
+### Build System
+
+* Add version file under sanic_openapi ([020338b](https://github.com/chenjr0719/sanic-openapi/commit/020338b))
+* Fix regex of version in setup.py ([ab01896](https://github.com/chenjr0719/sanic-openapi/commit/ab01896))
+* Use setup.py to control dependencies and remove requirements files ([1079e15](https://github.com/chenjr0719/sanic-openapi/commit/1079e15))
+
+
+### Tests
+
+* Add clean up in app fixture ([fa1b111](https://github.com/chenjr0719/sanic-openapi/commit/fa1b111))
+* Add config of coverage and integrate with setup.py ([30a9915](https://github.com/chenjr0719/sanic-openapi/commit/30a9915))
+* Add Sanic 19.06 to tox env ([8ad28cf](https://github.com/chenjr0719/sanic-openapi/commit/8ad28cf))
+* Add serialize_schema tests ([43b4c9d](https://github.com/chenjr0719/sanic-openapi/commit/43b4c9d))
+* Add test cases ([17ba469](https://github.com/chenjr0719/sanic-openapi/commit/17ba469))
+* Add tests for base fields ([2254f23](https://github.com/chenjr0719/sanic-openapi/commit/2254f23))
+* Add tests for decorators ([063afc3](https://github.com/chenjr0719/sanic-openapi/commit/063afc3))
+* Add tests for JsonBody field, List field, and Object field ([2a9f4d5](https://github.com/chenjr0719/sanic-openapi/commit/2a9f4d5))
+* Fix redirect test ([1539b04](https://github.com/chenjr0719/sanic-openapi/commit/1539b04))
+* Modify envlist in tox.ini to check compatibility of Sanic releases ([2c518b6](https://github.com/chenjr0719/sanic-openapi/commit/2c518b6))
+* Remove skip of static test case and fix options route test ([86a8a4a](https://github.com/chenjr0719/sanic-openapi/commit/86a8a4a))

CONTRIBUTING.md

@@ -86,6 +86,19 @@ black --verbose sanic_openapi tests
 isort --recursive sanic_openapi tests
 ```
 
+## Build Document
+
+Contribute documents of this project is also welcome. The document will be published on **Read the Docs** automatically. To preview the outputs, you can run the following commands to build the documents with `sphinx`:
+
+```shell
+cd docs
+make html
+```
+
+And you can open `docs/_build/html/index.html` to preview your works.
+
+> **Note:** Make sure you have install related modules. If you didn't, you can run `pip install -e .['doc']` to install all depedencies to build the documents.
+
 ## Make a Pull Request
 
 If you want to make a Pull Request, here are some suggestions:

README.md

@@ -8,7 +8,7 @@
 
 Give your Sanic API a UI and OpenAPI documentation, all for the price of free!
 
-![Example Swagger UI](images/code-to-ui.png?raw=true "Swagger UI")
+![Example Swagger UI](docs/_static/images/code-to-ui.png?raw=true "Swagger UI")
 
 ## Installation
 
@@ -29,155 +29,34 @@ Your routes will be automatically categorized by their blueprints.
 
 ## Example
 
-For an example Swagger UI, see the [Pet Store](http://petstore.swagger.io/)
-
-## Usage
-
-### Use simple decorators to document routes:
-
-```python
-from sanic_openapi import doc
-
-@app.get("/user/<user_id:int>")
-@doc.summary("Fetches a user by ID")
-@doc.produces({ "user": { "name": str, "id": int } })
-async def get_user(request, user_id):
-    ...
-
-@app.post("/user")
-@doc.summary("Creates a user")
-@doc.consumes(doc.JsonBody({"user": { "name": str }}), location="body")
-async def create_user(request):
-    ...
-```
-
-### Model your input/output
-
-```python
-class Car:
-    make = str
-    model = str
-    year = int
-
-class Garage:
-    spaces = int
-    cars = [Car]
-
-@app.get("/garage")
-@doc.summary("Gets the whole garage")
-@doc.produces(Garage)
-async def get_garage(request):
-    return json({
-        "spaces": 2,
-        "cars": [{"make": "Nissan", "model": "370Z"}]
-    })
-
-```
-
-### Get more descriptive
+Here is an example to use Sanic-OpenAPI:
 
 ```python
-class Car:
-    make = doc.String("Who made the car")
-    model = doc.String("Type of car.  This will vary by make")
-    year = doc.Integer("4-digit year of the car", required=False)
-
-class Garage:
-    spaces = doc.Integer("How many cars can fit in the garage")
-    cars = doc.List(Car, description="All cars in the garage")
-```
+from sanic import Sanic
+from sanic.response import json
+from sanic_openapi import swagger_blueprint
 
-### Specify a JSON body without extensive modelling
+app = Sanic()
+app.blueprint(swagger_blueprint)
 
-```python
-garage = doc.JsonBody({
-    "spaces": doc.Integer,
-    "cars": [
-        {
-            "make": doc.String,
-            "model": doc.String,
-            "year": doc.Integer
-        }
-    ]
-})
-
-@app.post("/store/garage")
-@doc.summary("Stores a garage object")
-@doc.consumes(garage, content_type="application/json", location="body")
-async def store_garage(request):
-    store_garage(request.json)
-    return json(request.json)
-```
 
-### Configure all the things
+@app.route("/")
+async def test(request):
+    return json({"hello": "world"})
 
-```python
-app.config.API_VERSION = '1.0.0'
-app.config.API_TITLE = 'Car API'
-app.config.API_DESCRIPTION = 'Car API'
-app.config.API_TERMS_OF_SERVICE = 'Use with caution!'
-app.config.API_PRODUCES_CONTENT_TYPES = ['application/json']
-app.config.API_CONTACT_EMAIL = 'channelcat@gmail.com'
-```
 
-By default, Sanic registers URIs both with and without a trailing `/`. You may specify the type of the shown URIs by setting `app.config.API_URI_FILTER` to one of the following values:
-- `all`: Include both types of URIs.
-- `slash`: Only include URIs with a trailing `/`.
-- All other values (and default): Only include URIs without a trailing `/`.
-
-#### Including OpenAPI's host, basePath and security parameters
-
-Just follow the OpenAPI 2.0 specification on this
-
-``` python
-app.config.API_HOST = 'subdomain.host.ext'
-app.config.API_BASEPATH = '/v2/api/'
-
-app.config.API_SECURITY = [
-    {
-        'authToken': []
-    }
-]
-
-app.config.API_SECURITY_DEFINITIONS = {
-    'authToken': {
-        'type': 'apiKey',
-        'in': 'header',
-        'name': 'Authorization',
-        'description': 'Paste your auth token and do not forget to add "Bearer " in front of it'
-    },
-    'OAuth2': {
-        'type': 'oauth2',
-        'flow': 'application',
-        'tokenUrl': 'https://your.authserver.ext/v1/token',
-        'scopes': {
-            'some_scope': 'Grants access to this API'
-        }
-    }
-}
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=8000)
 
 ```
 
-### Set Swagger-UI configuration parameters
+And you can get your Swagger document at <http://localhost:8000/swagger> like this:
+![](docs/_static/images/hello_world_example.png)
 
-Here you can set any configuration described in the swagger-ui documentation
+## Documentation
 
-```python
-app.config.SWAGGER_UI_CONFIGURATION = {
-    'validatorUrl': None, # Disable Swagger validator
-    'displayRequestDuration': True,
-    'docExpansion': 'full'
-}
-```
+Please check the documentation on [Readthedocs](https://sanic-openapi.readthedocs.io)
 
-### Set responses for different HTTP status codes
+## Contribution
 
-```python
-@app.get("/garage/<id>")
-@doc.summary("Gets the whole garage")
-@doc.produces(Garage)
-@doc.response(404, {"message": str}, description="When the garage cannot be found")
-async def get_garage(request, id):
-    garage = some_fetch_function(id)
-    return json(garage)
-```
+Any contribution is welcome. If you don't know how to getting started, please check issues first and check our [Contributing Guide](CONTRIBUTING.md) to start you contribution.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,4 @@
+img {
+    margin: 5px;
+    box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);
+}

docs/conf.py

@@ -0,0 +1,75 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+
+
+docs_directory = os.path.dirname(os.path.abspath(__file__))
+root_directory = os.path.dirname(docs_directory)
+sys.path.insert(0, root_directory)
+
+import sanic_openapi
+
+# -- Project information -----------------------------------------------------
+
+project = "Sanic-OpenAPI"
+copyright = "2019, Sanic Community"
+author = "Sanic Community"
+
+version = sanic_openapi.__version__
+release = sanic_openapi.__version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["recommonmark", "sphinx.ext.autodoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+master_doc = "index"
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
+
+from recommonmark.transform import AutoStructify
+
+
+def setup(app):
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            "enable_eval_rst": True,
+            "enable_auto_toc_tree": True,
+            # "auto_toc_tree_section": "Contents",
+        },
+        True,
+    )
+    app.add_transform(AutoStructify)