diff --git a/README.rst b/README.rst index ab25debf..b9414b0d 100644 --- a/README.rst +++ b/README.rst @@ -45,10 +45,8 @@ Hello World Example from sanic import Sanic from sanic.response import json - app = Sanic() - @app.route("/") async def test(request): return json({"hello": "world"}) @@ -56,21 +54,6 @@ Hello World Example if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) -SSL Example ------------ - -Optionally pass in an SSLContext: - -.. code:: python - - import ssl - certificate = "/path/to/certificate" - keyfile = "/path/to/keyfile" - context = ssl.create_default_context(purpose=ssl.Purpose.CLIENT_AUTH) - context.load_cert_chain(certificate, keyfile=keyfile) - - app.run(host="0.0.0.0", port=8443, ssl=context) - Installation ------------ @@ -79,12 +62,14 @@ Installation Documentation ------------- -Documentation can be found in the ``docs`` directory. +`Documentation on Readthedocs `_. .. |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 +.. |Documentation| image:: https://readthedocs.org/projects/sanic/badge/?version=latest + :target: http://sanic.readthedocs.io/en/latest/?badge=latest .. |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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..ef166d7d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Sanic +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) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index caf79901..c929e9e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,7 +75,7 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +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, @@ -153,3 +153,7 @@ epub_copyright = copyright epub_exclude_files = ['search.html'] + +# -- Custom Settings ------------------------------------------------------- + +suppress_warnings = ['image.nonlocal_uri'] diff --git a/docs/index.rst b/docs/index.rst index a8378a16..62cad021 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,21 +6,23 @@ Guides .. toctree:: :maxdepth: 2 + sanic/getting_started + sanic/routing + sanic/request_data + sanic/static_files + sanic/exceptions + sanic/middleware + sanic/blueprints + sanic/config + sanic/cookies + sanic/class_based_views + sanic/custom_protocol + sanic/ssl + sanic/testing + sanic/deploying + sanic/extensions + sanic/contributing getting_started - routing - request_data - deploying - static_files - middleware - exceptions - blueprints - class_based_views - config - cookies - custom_protocol - testing - extensions - contributing Module Documentation @@ -28,7 +30,5 @@ Module Documentation .. toctree:: - Module Reference <_api/sanic> - * :ref:`genindex` * :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..54191087 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=Sanic + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/blueprints.md b/docs/sanic/blueprints.md similarity index 97% rename from docs/blueprints.md rename to docs/sanic/blueprints.md index be95c5cc..71849ac1 100644 --- a/docs/blueprints.md +++ b/docs/sanic/blueprints.md @@ -158,7 +158,3 @@ app.blueprint(blueprint_v2) app.run(host='0.0.0.0', port=8000, debug=True) ``` - -**Previous:** [Exceptions](exceptions.md) - -**Next:** [Class-based views](class_based_views.md) diff --git a/docs/class_based_views.md b/docs/sanic/class_based_views.md similarity index 97% rename from docs/class_based_views.md rename to docs/sanic/class_based_views.md index 6ba1d567..5f99a0b5 100644 --- a/docs/class_based_views.md +++ b/docs/sanic/class_based_views.md @@ -106,7 +106,3 @@ view.add(['POST', 'PUT'], lambda request: text('I am a post/put method')) # Use the new view to handle requests to the base URL app.add_route(view, '/') ``` - -**Previous:** [Blueprints](blueprints.md) - -**Next:** [Cookies](cookies.md) diff --git a/docs/contributing.md b/docs/sanic/contributing.md similarity index 95% rename from docs/contributing.md rename to docs/sanic/contributing.md index dde57270..dbc64a02 100644 --- a/docs/contributing.md +++ b/docs/sanic/contributing.md @@ -31,5 +31,3 @@ 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. Please don't let this intimidate you! If you have any concerns about an idea, open an issue for discussion and help. - -**Previous:** [Sanic extensions](extensions.md) diff --git a/docs/cookies.md b/docs/sanic/cookies.md similarity index 95% rename from docs/cookies.md rename to docs/sanic/cookies.md index d593ed09..0a1042a2 100644 --- a/docs/cookies.md +++ b/docs/sanic/cookies.md @@ -73,7 +73,3 @@ parameters available: HTTPS. - `httponly` (boolean): Specifies whether the cookie cannot be read by Javascript. - -**Previous:** [Class-based views](class_based_views.md) - -**Next:** [Custom protocols](custom_protocol.md) diff --git a/docs/custom_protocol.md b/docs/sanic/custom_protocol.md similarity index 97% rename from docs/custom_protocol.md rename to docs/sanic/custom_protocol.md index 73d1f1d3..8355e8e9 100644 --- a/docs/custom_protocol.md +++ b/docs/sanic/custom_protocol.md @@ -70,7 +70,3 @@ async def response(request): app.run(host='0.0.0.0', port=8000, protocol=CustomHttpProtocol) ``` - -**Previous:** [Cookies](cookies.md) - -**Next:** [Testing](testing.md) diff --git a/docs/deploying.md b/docs/sanic/deploying.md similarity index 96% rename from docs/deploying.md rename to docs/sanic/deploying.md index f4d63163..0c526efe 100644 --- a/docs/deploying.md +++ b/docs/sanic/deploying.md @@ -53,7 +53,3 @@ directly run by the interpreter. if __name__ == '__main__': app.run(host='0.0.0.0', port=1337, workers=4) ``` - -**Previous:** [Request Data](request_data.md) - -**Next:** [Static Files](static_files.md) diff --git a/docs/exceptions.md b/docs/sanic/exceptions.md similarity index 94% rename from docs/exceptions.md rename to docs/sanic/exceptions.md index 8a294492..cffa219c 100644 --- a/docs/exceptions.md +++ b/docs/sanic/exceptions.md @@ -43,7 +43,3 @@ Some of the most useful exceptions are presented below: usually occurs if there is an exception raised in user code. See the `sanic.exceptions` module for the full list of exceptions to throw. - -**Previous:** [Middleware](middleware.md) - -**Next:** [Blueprints](blueprints.md) diff --git a/docs/extensions.md b/docs/sanic/extensions.md similarity index 77% rename from docs/extensions.md rename to docs/sanic/extensions.md index 1cf6121b..8303311a 100644 --- a/docs/extensions.md +++ b/docs/sanic/extensions.md @@ -1,4 +1,4 @@ -# Sanic Extensions +# Extensions A list of Sanic extensions created by the community. @@ -6,7 +6,3 @@ A list of Sanic extensions created by the community. Allows using redis, memcache or an in memory store. - [CORS](https://github.com/ashleysommer/sanic-cors): A port of flask-cors. - [Jinja2](https://github.com/lixxu/sanic-jinja2): Support for Jinja2 template. - -**Previous:** [Testing](testing.md) - -**Next:** [Contributing](contributing.md) diff --git a/docs/getting_started.md b/docs/sanic/getting_started.md similarity index 95% rename from docs/getting_started.md rename to docs/sanic/getting_started.md index e3a2a31b..04d22248 100644 --- a/docs/getting_started.md +++ b/docs/sanic/getting_started.md @@ -25,5 +25,3 @@ syntax, so earlier versions of python won't work. the message *Hello world!*. You now have a working Sanic server! - -**Next:** [Routing](routing.md) diff --git a/docs/middleware.md b/docs/sanic/middleware.md similarity index 96% rename from docs/middleware.md rename to docs/sanic/middleware.md index 6adb9328..58ff8feb 100644 --- a/docs/middleware.md +++ b/docs/sanic/middleware.md @@ -64,7 +64,3 @@ async def halt_request(request): async def halt_response(request, response): return text('I halted the response') ``` - -**Previous:** [Static Files](static_files.md) - -**Next:** [Exceptions](exceptions.md) diff --git a/docs/request_data.md b/docs/sanic/request_data.md similarity index 97% rename from docs/request_data.md rename to docs/sanic/request_data.md index 555cf765..c1eea5c1 100644 --- a/docs/request_data.md +++ b/docs/sanic/request_data.md @@ -89,7 +89,3 @@ args.get('titles') # => 'Post 1' args.getlist('titles') # => ['Post 1', 'Post 2'] ``` - -**Previous:** [Routing](routing.md) - -**Next:** [Deploying](deploying.md) diff --git a/docs/routing.md b/docs/sanic/routing.md similarity index 96% rename from docs/routing.md rename to docs/sanic/routing.md index d88bcf26..9d5856d6 100644 --- a/docs/routing.md +++ b/docs/sanic/routing.md @@ -105,7 +105,3 @@ app.add_route(handler1, '/test') app.add_route(handler2, '/folder/') app.add_route(person_handler2, '/person/', methods=['GET']) ``` - -**Previous:** [Getting Started](getting_started.md) - -**Next:** [Request Data](request_data.md) diff --git a/docs/sanic/ssl.rst b/docs/sanic/ssl.rst new file mode 100644 index 00000000..ef2cfd34 --- /dev/null +++ b/docs/sanic/ssl.rst @@ -0,0 +1,12 @@ +SSL Example +----------- + +Optionally pass in an SSLContext: + +.. code:: python + + import ssl + context = ssl.create_default_context(purpose=ssl.Purpose.CLIENT_AUTH) + context.load_cert_chain("/path/to/cert", keyfile="/path/to/keyfile") + + app.run(host="0.0.0.0", port=8443, ssl=context) \ No newline at end of file diff --git a/docs/static_files.md b/docs/sanic/static_files.md similarity index 87% rename from docs/static_files.md rename to docs/sanic/static_files.md index 5daf7818..d7e4866d 100644 --- a/docs/static_files.md +++ b/docs/sanic/static_files.md @@ -17,7 +17,3 @@ app.static('/the_best.png', '/home/ubuntu/test.png') app.run(host="0.0.0.0", port=8000) ``` - -**Previous:** [Deploying](deploying.md) - -**Next:** [Middleware](middleware.md) diff --git a/docs/testing.md b/docs/sanic/testing.md similarity index 95% rename from docs/testing.md rename to docs/sanic/testing.md index bdb85efb..79c719e8 100644 --- a/docs/testing.md +++ b/docs/sanic/testing.md @@ -49,7 +49,3 @@ def test_endpoint_challenge(): # Assert that the server responds with the challenge string assert response.text == request_data['challenge'] ``` - -**Previous:** [Custom protocols](custom_protocol.md) - -**Next:** [Sanic extensions](extensions.md) diff --git a/requirements-dev.txt b/requirements-dev.txt index b41bb274..64542931 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -13,5 +13,6 @@ falcon tornado aiofiles sphinx +sphinx_rtd_theme recommonmark beautifulsoup4