From 7654c2f90209a6e4cad4bd8bac6fd9a428c9b41f Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Sun, 25 Dec 2016 20:20:48 +1100 Subject: [PATCH 1/7] Use Sphinx for documentation. This commit creates configuration files and an index page for documentation using Sphinx. The recommonmark package is used to enable Markdown support for Sphinx, using the Common Mark specification. This means that the current documentation doesn't need to be rewritten. --- .gitignore | 3 + docs/conf.py | 155 +++++++++++++++++++++++++++++++++++++++++++ docs/contributing.md | 17 ++++- docs/index.rst | 90 +++++++++++++++++++++++++ requirements-dev.txt | 2 + 5 files changed, 266 insertions(+), 1 deletion(-) create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/.gitignore b/.gitignore index d7872c5c..535c6a2f 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,6 @@ settings.py *.pyc .idea/* .cache/* +docs/_build/ +docs/sanic.rst +docs/modules.rst \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..caf79901 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,155 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Sanic documentation build configuration file, created by +# sphinx-quickstart on Sun Dec 25 18:07:21 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. + +import os +import sys + +# Add support for Markdown documentation using Recommonmark +from recommonmark.parser import CommonMarkParser + +# Ensure that sanic is present in the path, to allow sphinx-apidoc to +# autogenerate documentation from docstrings +root_directory = os.path.dirname(os.getcwd()) +sys.path.insert(0, root_directory) + +import sanic + +# -- General configuration ------------------------------------------------ + +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages'] + +templates_path = ['_templates'] + +# Enable support for both Restructured Text and Markdown +source_parsers = {'.md': CommonMarkParser} +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Sanic' +copyright = '2016, Sanic contributors' +author = 'Sanic contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = sanic.__version__ +# The full version, including alpha/beta/rc tags. +release = sanic.__version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +# +# modules.rst is generated by sphinx-apidoc but is unused. This suppresses +# a warning about it. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'modules.rst'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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 = 'alabaster' + +# 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Sanicdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Sanic.tex', 'Sanic Documentation', + 'Sanic contributors', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'sanic', 'Sanic Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Sanic', 'Sanic Documentation', + author, 'Sanic', 'One line description of project.', + 'Miscellaneous'), +] + + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + diff --git a/docs/contributing.md b/docs/contributing.md index e39a7247..c046bd39 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,5 +6,20 @@ Thank you for your interest! * `python -m pip install pytest` * `python -m pytest tests` +## Documentation + +Sanic's documentation is built using [sphinx](http://www.sphinx-doc.org/en/1.5.1/). Guides are written in Markdown and can be found in the `docs` folder, while the module reference is automatically generated using `sphinx-apidoc`. + +To generate the documentation from scratch: + +```bash +rm -f docs/sanic.rst +rm -f docs/modules.rst +sphinx-apidoc -o docs/ sanic +sphinx-build -b html docs docs/_build +``` + +The HTML documentation will be created in the `docs/_build` folder. + ## Warning -One of the main goals of Sanic is speed. Code that lowers the performance of Sanic without significant gains in usability, security, or features may not be merged. \ No newline at end of file +One of the main goals of Sanic is speed. Code that lowers the performance of Sanic without significant gains in usability, security, or features may not be merged. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..1e815582 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,90 @@ +Welcome to Sanic's documentation! +================================= + +Sanic is a Flask-like Python 3.5+ web server that's written to go fast. It's based on the work done by the amazing folks at magicstack, and was inspired by `this article `_. + +On top of being Flask-like, Sanic supports async request handlers. This means you can use the new shiny async/await syntax from Python 3.5, making your code non-blocking and speedy. + +Sanic is developed `on GitHub `_. Contributions are welcome! + +Benchmarks +---------- + +All tests were run on an AWS medium instance running ubuntu, using 1 +process. Each script delivered a small JSON response and was tested with +wrk using 100 connections. Pypy was tested for Falcon and Flask but did +not speed up requests. + ++-----------+-----------------------+----------------+---------------+ +| Server | Implementation | Requests/sec | Avg Latency | ++===========+=======================+================+===============+ +| Sanic | Python 3.5 + uvloop | 33,342 | 2.96ms | ++-----------+-----------------------+----------------+---------------+ +| Wheezy | gunicorn + meinheld | 20,244 | 4.94ms | ++-----------+-----------------------+----------------+---------------+ +| Falcon | gunicorn + meinheld | 18,972 | 5.27ms | ++-----------+-----------------------+----------------+---------------+ +| Bottle | gunicorn + meinheld | 13,596 | 7.36ms | ++-----------+-----------------------+----------------+---------------+ +| Flask | gunicorn + meinheld | 4,988 | 20.08ms | ++-----------+-----------------------+----------------+---------------+ +| Kyoukai | Python 3.5 + uvloop | 3,889 | 27.44ms | ++-----------+-----------------------+----------------+---------------+ +| Aiohttp | Python 3.5 + uvloop | 2,979 | 33.42ms | ++-----------+-----------------------+----------------+---------------+ +| Tornado | Python 3.5 | 2,138 | 46.66ms | ++-----------+-----------------------+----------------+---------------+ + +Hello World Example +------------------- + +.. code:: python + + from sanic import Sanic + from sanic.response import json + + + app = Sanic() + + + @app.route("/") + async def test(request): + return json({"hello": "world"}) + + if __name__ == "__main__": + app.run(host="0.0.0.0", port=8000) + +Installation +------------ + +- ``python -m pip install sanic`` + +Guides +====== + +.. toctree:: + :maxdepth: 2 + + getting_started + request_data + routing + middleware + exceptions + blueprints + class_based_views + cookies + static_files + testing + deploying + contributing + + +Module Documentation +==================== + +.. toctree:: + + Module Reference + +* :ref:`genindex` +* :ref:`search` diff --git a/requirements-dev.txt b/requirements-dev.txt index 1c34d695..780c8677 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -12,3 +12,5 @@ kyoukai falcon tornado aiofiles +sphinx +recommonmark From 52c59e71333ac81b0afbee6d92973f85be7d71c9 Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Sun, 25 Dec 2016 20:43:45 +1100 Subject: [PATCH 2/7] Fix all docstring errors. When generating documentation with sphinx-apidoc, there are currently many docstring errors, mostly minor. This commit fixes all errors. --- sanic/exceptions.py | 1 + sanic/request.py | 1 + sanic/router.py | 14 ++++++++++++-- sanic/sanic.py | 21 ++++++++++++++------- sanic/server.py | 7 +++++-- sanic/static.py | 4 +++- sanic/views.py | 10 +++++++--- 7 files changed, 43 insertions(+), 15 deletions(-) diff --git a/sanic/exceptions.py b/sanic/exceptions.py index 369a87a2..68051ebe 100644 --- a/sanic/exceptions.py +++ b/sanic/exceptions.py @@ -51,6 +51,7 @@ class Handler: def response(self, request, exception): """ Fetches and executes an exception handler and returns a response object + :param request: Request :param exception: Exception to handle :return: Response object diff --git a/sanic/request.py b/sanic/request.py index 62d89781..adbb1e0d 100644 --- a/sanic/request.py +++ b/sanic/request.py @@ -132,6 +132,7 @@ File = namedtuple('File', ['type', 'body', 'name']) def parse_multipart_form(body, boundary): """ Parses a request body and returns fields and files + :param body: Bytes request body :param boundary: Bytes multipart boundary :return: fields (RequestParameters), files (RequestParameters) diff --git a/sanic/router.py b/sanic/router.py index 4cc1f073..57d92dd5 100644 --- a/sanic/router.py +++ b/sanic/router.py @@ -26,11 +26,19 @@ class RouteExists(Exception): class Router: """ Router supports basic routing with parameters and method checks + Usage: + + .. code-block:: python + @sanic.route('/my/url/', methods=['GET', 'POST', ...]) def my_route(request, my_parameter): do stuff... + or + + .. code-block:: python + @sanic.route('/my/url/:type', methods['GET', 'POST', ...]) def my_route_with_type(request, my_parameter): do stuff... @@ -55,11 +63,12 @@ class Router: def add(self, uri, methods, handler): """ Adds a handler to the route list + :param uri: Path to match :param methods: Array of accepted method names. - If none are provided, any method is allowed + If none are provided, any method is allowed :param handler: Request handler function. - When executed, it should provide a response object. + When executed, it should provide a response object. :return: Nothing """ if uri in self.routes_all: @@ -113,6 +122,7 @@ class Router: """ Gets a request handler based on the URL of the request, or raises an error + :param request: Request object :return: handler, arguments, keyword arguments """ diff --git a/sanic/sanic.py b/sanic/sanic.py index f48b2bd5..67132f45 100644 --- a/sanic/sanic.py +++ b/sanic/sanic.py @@ -44,6 +44,7 @@ class Sanic: def route(self, uri, methods=None): """ Decorates a function to be registered as a route + :param uri: path of the URL :param methods: list or tuple of methods allowed :return: decorated function @@ -65,6 +66,7 @@ class Sanic: A helper method to register class instance or functions as a handler to the application url routes. + :param handler: function or class instance :param uri: path of the URL :param methods: list or tuple of methods allowed @@ -77,7 +79,8 @@ class Sanic: def exception(self, *exceptions): """ Decorates a function to be registered as a handler for exceptions - :param *exceptions: exceptions + + :param \*exceptions: exceptions :return: decorated function """ @@ -123,6 +126,7 @@ class Sanic: def blueprint(self, blueprint, **options): """ Registers a blueprint on the application. + :param blueprint: Blueprint object :param options: option dictionary with blueprint defaults :return: Nothing @@ -155,9 +159,10 @@ class Sanic: Takes a request from the HTTP Server and returns a response object to be sent back The HTTP Server only expects a response object, so exception handling must be done here + :param request: HTTP Request object :param response_callback: Response function to be called with the - response as the only argument + response as the only argument :return: Nothing """ try: @@ -236,20 +241,21 @@ class Sanic: """ Runs the HTTP Server and listens until keyboard interrupt or term signal. On termination, drains connections before closing. + :param host: Address to host on :param port: Port to host on :param debug: Enables debug output (slows server) :param before_start: Function to be executed before the server starts - accepting connections + accepting connections :param after_start: Function to be executed after the server starts - accepting connections + accepting connections :param before_stop: Function to be executed when a stop signal is - received before it is respected + received before it is respected :param after_stop: Function to be executed when all requests are - complete + complete :param sock: Socket for the server to accept connections from :param workers: Number of processes - received before it is respected + received before it is respected :param loop: asyncio compatible event loop :return: Nothing """ @@ -324,6 +330,7 @@ class Sanic: """ Starts multiple server processes simultaneously. Stops on interrupt and terminate signals, and drains connections when complete. + :param server_settings: kw arguments to be passed to the serve function :param workers: number of workers to launch :param stop_event: if provided, is used as a stop signal diff --git a/sanic/server.py b/sanic/server.py index 11756005..725104f0 100644 --- a/sanic/server.py +++ b/sanic/server.py @@ -201,6 +201,7 @@ def update_current_time(loop): """ Caches the current time, since it is needed at the end of every keep-alive request to update the request timeout time + :param loop: :return: """ @@ -229,13 +230,15 @@ def serve(host, port, request_handler, error_handler, before_start=None, request_max_size=None, reuse_port=False, loop=None): """ Starts asynchronous HTTP Server on an individual process. + :param host: Address to host on :param port: Port to host on :param request_handler: Sanic request handler with middleware :param after_start: Function to be executed after the server starts - listening. Takes single argument `loop` + listening. Takes single argument `loop` :param before_stop: Function to be executed when a stop signal is - received before it is respected. Takes single argumenet `loop` + received before it is respected. Takes single + argumenet `loop` :param debug: Enables debug output (slows server) :param request_timeout: time in seconds :param sock: Socket for the server to accept connections from diff --git a/sanic/static.py b/sanic/static.py index 9f5f2d52..1d0bff0f 100644 --- a/sanic/static.py +++ b/sanic/static.py @@ -15,12 +15,14 @@ def register(app, uri, file_or_directory, pattern, use_modified_since): """ Registers a static directory handler with Sanic by adding a route to the router and registering a handler. + :param app: Sanic :param file_or_directory: File or directory path to serve from :param uri: URL to serve from :param pattern: regular expression used to match files in the URL :param use_modified_since: If true, send file modified time, and return - not modified if the browser's matches the server's + not modified if the browser's matches the + server's """ # If we're not trying to match a file directly, diff --git a/sanic/views.py b/sanic/views.py index 9387bcf6..9509b5ee 100644 --- a/sanic/views.py +++ b/sanic/views.py @@ -7,21 +7,25 @@ class HTTPMethodView: to every HTTP method you want to support. For example: - class DummyView(View): + .. code-block:: python + + class DummyView(View): def get(self, request, *args, **kwargs): return text('I am get method') - def put(self, request, *args, **kwargs): return text('I am put method') + etc. If someone tries to use a non-implemented method, there will be a 405 response. If you need any url params just mention them in method definition: - class DummyView(View): + .. code-block:: python + + class DummyView(View): def get(self, request, my_param_here, *args, **kwargs): return text('I am get method with %s' % my_param_here) From 34d1e5e67ed9b302c4d4824ea09f948a02ead69e Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Tue, 10 Jan 2017 09:28:33 +1100 Subject: [PATCH 3/7] Convert README to RestructuredText and include it in the documentation index. --- README.md | 96 -------------------------------------------------- README.rst | 76 +++++++++++++++++++++++++++++++++++++++ docs/index.rst | 61 +------------------------------- 3 files changed, 77 insertions(+), 156 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index e417b4a1..00000000 --- a/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Sanic - -[![Join the chat at https://gitter.im/sanic-python/Lobby](https://badges.gitter.im/sanic-python/Lobby.svg)](https://gitter.im/sanic-python/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -[![Build Status](https://travis-ci.org/channelcat/sanic.svg?branch=master)](https://travis-ci.org/channelcat/sanic) -[![PyPI](https://img.shields.io/pypi/v/sanic.svg)](https://pypi.python.org/pypi/sanic/) -[![PyPI](https://img.shields.io/pypi/pyversions/sanic.svg)](https://pypi.python.org/pypi/sanic/) - -Sanic is a Flask-like Python 3.5+ web server that's written to go fast. It's based on the work done by the amazing folks at magicstack, and was inspired by this article: https://magic.io/blog/uvloop-blazing-fast-python-networking/. - -On top of being Flask-like, Sanic supports async request handlers. This means you can use the new shiny async/await syntax from Python 3.5, making your code non-blocking and speedy. - -## Benchmarks - -All tests were run on an AWS medium instance running ubuntu, using 1 process. Each script delivered a small JSON response and was tested with wrk using 100 connections. Pypy was tested for Falcon and Flask but did not speed up requests. - - - -| Server | Implementation | Requests/sec | Avg Latency | -| ------- | ------------------- | ------------:| -----------:| -| Sanic | Python 3.5 + uvloop | 33,342 | 2.96ms | -| Wheezy | gunicorn + meinheld | 20,244 | 4.94ms | -| Falcon | gunicorn + meinheld | 18,972 | 5.27ms | -| Bottle | gunicorn + meinheld | 13,596 | 7.36ms | -| Flask | gunicorn + meinheld | 4,988 | 20.08ms | -| Kyoukai | Python 3.5 + uvloop | 3,889 | 27.44ms | -| Aiohttp | Python 3.5 + uvloop | 2,979 | 33.42ms | -| Tornado | Python 3.5 | 2,138 | 46.66ms | - -## Hello World - -```python -from sanic import Sanic -from sanic.response import json - - -app = Sanic() - - -@app.route("/") -async def test(request): - return json({"hello": "world"}) - -if __name__ == "__main__": - app.run(host="0.0.0.0", port=8000) - -``` - -## Installation - * `python -m pip install sanic` - -## Documentation - * [Getting started](docs/getting_started.md) - * [Request Data](docs/request_data.md) - * [Routing](docs/routing.md) - * [Middleware](docs/middleware.md) - * [Exceptions](docs/exceptions.md) - * [Blueprints](docs/blueprints.md) - * [Class Based Views](docs/class_based_views.md) - * [Cookies](docs/cookies.md) - * [Static Files](docs/static_files.md) - * [Testing](docs/testing.md) - * [Deploying](docs/deploying.md) - * [Contributing](docs/contributing.md) - * [License](LICENSE) - -## TODO: - * Streamed file processing - * File output - * Examples of integrations with 3rd-party modules - * RESTful router - -## Limitations: - * No wheels for uvloop and httptools on Windows :( - -## Final Thoughts: - - ▄▄▄▄▄ - ▀▀▀██████▄▄▄ _______________ - ▄▄▄▄▄ █████████▄ / \ - ▀▀▀▀█████▌ ▀▐▄ ▀▐█ | Gotta go fast! | - ▀▀█████▄▄ ▀██████▄██ | _________________/ - ▀▄▄▄▄▄ ▀▀█▄▀█════█▀ |/ - ▀▀▀▄ ▀▀███ ▀ ▄▄ - ▄███▀▀██▄████████▄ ▄▀▀▀▀▀▀█▌ - ██▀▄▄▄██▀▄███▀ ▀▀████ ▄██ - ▄▀▀▀▄██▄▀▀▌████▒▒▒▒▒▒███ ▌▄▄▀ - ▌ ▐▀████▐███▒▒▒▒▒▐██▌ - ▀▄▄▄▄▀ ▀▀████▒▒▒▒▄██▀ - ▀▀█████████▀ - ▄▄██▀██████▀█ - ▄██▀ ▀▀▀ █ - ▄█ ▐▌ - ▄▄▄▄█▌ ▀█▄▄▄▄▀▀▄ - ▌ ▐ ▀▀▄▄▄▀ - ▀▀▄▄▀ diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..eb04b6a5 --- /dev/null +++ b/README.rst @@ -0,0 +1,76 @@ +Sanic +================================= + +|Join the chat at https://gitter.im/sanic-python/Lobby| |Build Status| |PyPI| |PyPI version| + +Sanic is a Flask-like Python 3.5+ web server that's written to go fast. It's based on the work done by the amazing folks at magicstack, and was inspired by `this article `_. + +On top of being Flask-like, Sanic supports async request handlers. This means you can use the new shiny async/await syntax from Python 3.5, making your code non-blocking and speedy. + +Sanic is developed `on GitHub `_. Contributions are welcome! + +Benchmarks +---------- + +All tests were run on an AWS medium instance running ubuntu, using 1 +process. Each script delivered a small JSON response and was tested with +wrk using 100 connections. Pypy was tested for Falcon and Flask but did +not speed up requests. + ++-----------+-----------------------+----------------+---------------+ +| Server | Implementation | Requests/sec | Avg Latency | ++===========+=======================+================+===============+ +| Sanic | Python 3.5 + uvloop | 33,342 | 2.96ms | ++-----------+-----------------------+----------------+---------------+ +| Wheezy | gunicorn + meinheld | 20,244 | 4.94ms | ++-----------+-----------------------+----------------+---------------+ +| Falcon | gunicorn + meinheld | 18,972 | 5.27ms | ++-----------+-----------------------+----------------+---------------+ +| Bottle | gunicorn + meinheld | 13,596 | 7.36ms | ++-----------+-----------------------+----------------+---------------+ +| Flask | gunicorn + meinheld | 4,988 | 20.08ms | ++-----------+-----------------------+----------------+---------------+ +| Kyoukai | Python 3.5 + uvloop | 3,889 | 27.44ms | ++-----------+-----------------------+----------------+---------------+ +| Aiohttp | Python 3.5 + uvloop | 2,979 | 33.42ms | ++-----------+-----------------------+----------------+---------------+ +| Tornado | Python 3.5 | 2,138 | 46.66ms | ++-----------+-----------------------+----------------+---------------+ + +Hello World Example +------------------- + +.. code:: python + + from sanic import Sanic + from sanic.response import json + + + app = Sanic() + + + @app.route("/") + async def test(request): + return json({"hello": "world"}) + + if __name__ == "__main__": + app.run(host="0.0.0.0", port=8000) + +Installation +------------ + +- ``python -m pip install sanic`` + +Documentation +------------- + +Documentation can be found in the ``docs`` directory. + +.. |Join the chat at https://gitter.im/sanic-python/Lobby| image:: https://badges.gitter.im/sanic-python/Lobby.svg + :target: https://gitter.im/sanic-python/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +.. |Build Status| image:: https://travis-ci.org/channelcat/sanic.svg?branch=master + :target: https://travis-ci.org/channelcat/sanic +.. |PyPI| image:: https://img.shields.io/pypi/v/sanic.svg + :target: https://pypi.python.org/pypi/sanic/ +.. |PyPI version| image:: https://img.shields.io/pypi/pyversions/sanic.svg + :target: https://pypi.python.org/pypi/sanic/ diff --git a/docs/index.rst b/docs/index.rst index 1e815582..264ebc93 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,63 +1,4 @@ -Welcome to Sanic's documentation! -================================= - -Sanic is a Flask-like Python 3.5+ web server that's written to go fast. It's based on the work done by the amazing folks at magicstack, and was inspired by `this article `_. - -On top of being Flask-like, Sanic supports async request handlers. This means you can use the new shiny async/await syntax from Python 3.5, making your code non-blocking and speedy. - -Sanic is developed `on GitHub `_. Contributions are welcome! - -Benchmarks ----------- - -All tests were run on an AWS medium instance running ubuntu, using 1 -process. Each script delivered a small JSON response and was tested with -wrk using 100 connections. Pypy was tested for Falcon and Flask but did -not speed up requests. - -+-----------+-----------------------+----------------+---------------+ -| Server | Implementation | Requests/sec | Avg Latency | -+===========+=======================+================+===============+ -| Sanic | Python 3.5 + uvloop | 33,342 | 2.96ms | -+-----------+-----------------------+----------------+---------------+ -| Wheezy | gunicorn + meinheld | 20,244 | 4.94ms | -+-----------+-----------------------+----------------+---------------+ -| Falcon | gunicorn + meinheld | 18,972 | 5.27ms | -+-----------+-----------------------+----------------+---------------+ -| Bottle | gunicorn + meinheld | 13,596 | 7.36ms | -+-----------+-----------------------+----------------+---------------+ -| Flask | gunicorn + meinheld | 4,988 | 20.08ms | -+-----------+-----------------------+----------------+---------------+ -| Kyoukai | Python 3.5 + uvloop | 3,889 | 27.44ms | -+-----------+-----------------------+----------------+---------------+ -| Aiohttp | Python 3.5 + uvloop | 2,979 | 33.42ms | -+-----------+-----------------------+----------------+---------------+ -| Tornado | Python 3.5 | 2,138 | 46.66ms | -+-----------+-----------------------+----------------+---------------+ - -Hello World Example -------------------- - -.. code:: python - - from sanic import Sanic - from sanic.response import json - - - app = Sanic() - - - @app.route("/") - async def test(request): - return json({"hello": "world"}) - - if __name__ == "__main__": - app.run(host="0.0.0.0", port=8000) - -Installation ------------- - -- ``python -m pip install sanic`` +.. include:: ../README.rst Guides ====== From 385328ffd5e640b063b7b0ae3a1a00eedc79308e Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Tue, 10 Jan 2017 09:41:00 +1100 Subject: [PATCH 4/7] Generate API documentation in the _api folder --- .gitignore | 3 +-- docs/contributing.md | 5 ++--- docs/index.rst | 2 +- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 535c6a2f..9050c413 100644 --- a/.gitignore +++ b/.gitignore @@ -10,5 +10,4 @@ settings.py .idea/* .cache/* docs/_build/ -docs/sanic.rst -docs/modules.rst \ No newline at end of file +docs/_api/ diff --git a/docs/contributing.md b/docs/contributing.md index c046bd39..a40654cc 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -13,9 +13,8 @@ Sanic's documentation is built using [sphinx](http://www.sphinx-doc.org/en/1.5.1 To generate the documentation from scratch: ```bash -rm -f docs/sanic.rst -rm -f docs/modules.rst -sphinx-apidoc -o docs/ sanic +rm -f docs/_api/* +sphinx-apidoc -o docs/_api/ sanic sphinx-build -b html docs docs/_build ``` diff --git a/docs/index.rst b/docs/index.rst index 264ebc93..b28d97f7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,7 +25,7 @@ Module Documentation .. toctree:: - Module Reference + Module Reference <_api/sanic> * :ref:`genindex` * :ref:`search` From ebce7b01c7b94521a01f891ca51f435ac398aae3 Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Thu, 19 Jan 2017 08:54:20 +1100 Subject: [PATCH 5/7] Add new guides to documentation index --- docs/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index b28d97f7..202a6d50 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,8 +15,10 @@ Guides class_based_views cookies static_files + custom_protocol testing deploying + extensions contributing From 5cfd8b9aa8c68c6a65cf39009dbdf647402ed48b Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Thu, 19 Jan 2017 08:58:13 +1100 Subject: [PATCH 6/7] Fix formatting of 'Final Word' in README --- README.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.rst b/README.rst index 20352071..a95081cc 100644 --- a/README.rst +++ b/README.rst @@ -89,6 +89,8 @@ Limitations Final Thoughts -------------- +:: + ▄▄▄▄▄ ▀▀▀██████▄▄▄ _______________ ▄▄▄▄▄ █████████▄ / \ From 30862c0a3e90dcaa0c19890a919ea89f1e5970c8 Mon Sep 17 00:00:00 2001 From: Cadel Watson Date: Fri, 20 Jan 2017 09:32:08 +1100 Subject: [PATCH 7/7] Update documentation generation instructions. --- docs/contributing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index a40654cc..667978ca 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -13,8 +13,7 @@ Sanic's documentation is built using [sphinx](http://www.sphinx-doc.org/en/1.5.1 To generate the documentation from scratch: ```bash -rm -f docs/_api/* -sphinx-apidoc -o docs/_api/ sanic +sphinx-apidoc -fo docs/_api/ sanic sphinx-build -b html docs docs/_build ```