From 18d44704fc12d7ff2530da20b5a051a04ddff4e3 Mon Sep 17 00:00:00 2001 From: Dave Shawley Date: Wed, 22 Jul 2015 13:40:55 -0400 Subject: [PATCH] Add documentation --- MANIFEST.in | 1 + README.rst | 33 ++++++++++++- docs/conf.py | 40 +++++++++++++++ docs/contributing.rst | 112 ++++++++++++++++++++++++++++++++++++++++++ docs/history.rst | 7 +++ docs/index.rst | 7 +++ setup.cfg | 2 + 7 files changed, 200 insertions(+), 2 deletions(-) create mode 100644 docs/conf.py create mode 100644 docs/contributing.rst create mode 100644 docs/history.rst create mode 100644 docs/index.rst create mode 100644 setup.cfg diff --git a/MANIFEST.in b/MANIFEST.in index 505d963..1705c55 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,3 @@ include LICENSE +graft docs graft requires diff --git a/README.rst b/README.rst index 5d7f678..18c9b2b 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,32 @@ -Sprockets.HTTP +sprockets.http ============== -HTTP Server / Web application controller +This library runs Tornado HTTP server applications intelligently. + +* ``SIGTERM`` is gracefully handled with respect to outstanding timeouts + and callbacks +* Listening port is configured by the ``PORT`` environment variable +* ``logging`` layer is configured to output JSON by default +* *"Debug mode"* is enabled by the ``DEBUG`` environment variable + + - makes log out human-readable + - catches ``SIGINT`` (e.g., ``Ctrl+C``) + - application run in a single process + +Example Usage +------------- + +.. code-block:: python + + from tornado import web + import sprockets.http + + + def make_app(**settings): + return web.Application([ + # insert your handlers + ], **settings) + + + if __name__ == '__main__': + sprockets.http.run(make_app) + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..7c88dd7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- +import alabaster +from sprockets import http + +project = 'sprockets.http' +copyright = 'AWeber Communications, Inc.' +version = http.__version__ +release = '.'.join(str(v) for v in http.version_info[0:2]) + +needs_sphinx = '1.0' +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', + 'sphinxcontrib.autohttp.tornado', +] + +templates_path = [] +source_suffix = '.rst' +source_encoding = 'utf-8-sig' +master_doc = 'index' +exclude_patterns = [] +pygments_style = 'sphinx' +html_theme = 'alabaster' +html_theme_path = [alabaster.get_path()] +html_sidebars = { + '**': ['about.html', 'navigation.html'], +} +html_theme_options = { + 'github_user': 'sprockets', + 'github_repo': 'sprockets.http', + 'description': 'Tornado application runner', + 'github_banner': True, + 'travis_button': True, +} + +intersphinx_mapping = { + 'python': ('http://docs.python.org/3/', None), + 'tornado': ('http://tornadoweb.org/en/latest/', None), +} diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..8b58b97 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,112 @@ +How to Contribute +================= +Do you want to contribute fixes or improvements? + + **AWesome!** *Thank you very much, and let's get started.* + +Set up a development environment +-------------------------------- +The first thing that you need is a development environment so that you can +run the test suite, update the documentation, and everything else that is +involved in contributing. The easiest way to do that is to create a virtual +environment for your endevours:: + + $ virtualenv -p python2.7 env + +Don't worry about writing code against previous versions of Python unless +you you don't have a choice. That is why we run our tests through `tox`_. +If you don't have a choice, then install `virtualenv`_ to create the +environment instead. The next step is to install the development tools +that this project uses. These are listed in *requires/development.txt*:: + + $ env/bin/pip install -qr requires/development.txt + +At this point, you will have everything that you need to develop at your +disposal. *setup.py* is the swiss-army knife in your development tool +chest. It provides the following commands: + +**./setup.py nosetests** + Run the test suite using `nose`_ and generate a nice coverage report. + +**./setup.py build_sphinx** + Generate the documentation using `sphinx`_. + +**./setup.py flake8** + Run `flake8`_ over the code and report style violations. + +If any of the preceding commands give you problems, then you will have to +fix them **before** your pull request will be accepted. + +Running Tests +------------- +The easiest (and quickest) way to run the test suite is to use the +*nosetests* command. It will run the test suite against the currently +installed python version and report not only the test result but the +test coverage as well:: + + $ ./setup.py nosetests + + running nosetests + running egg_info + writing dependency_links to sprockets.http.egg-info/dependency_links.txt + writing top-level names to sprockets.http.egg-info/top_level.txt + writing sprockets.http.egg-info/PKG-INFO + reading manifest file 'sprockets.http.egg-info/SOURCES.txt' + reading manifest template 'MANIFEST.in' + warning: no previously-included files matching '__pycache__'... + warning: no previously-included files matching '*.swp' found ... + writing manifest file 'sprockets.http.egg-info/SOURCES.txt' + ... + + Name Stmts Miss Branch BrMiss Cover Missing + ---------------------------------------------------------------------- + ... + ---------------------------------------------------------------------- + TOTAL 95 2 59 2 97% + ---------------------------------------------------------------------- + Ran 44 tests in 0.054s + + OK + +That's the quick way to run tests. The slightly longer way is to run +the `detox`_ utility. It will run the test suite against all of the +supported python versions in parallel. This is essentially what Travis-CI +will do when you issue a pull request anyway:: + + $ env/bin/detox + py27 recreate: /.../sprockets.http/build/tox/py27 + GLOB sdist-make: /.../sprockets.http/setup.py + py34 recreate: /.../sprockets.http/build/tox/py34 + py27 installdeps: -rtest-requirements.txt, mock + py34 installdeps: -rtest-requirements.txt + py27 inst: /.../sprockets.http/build/tox/dist/sprockets.http-0.0.0.zip + py27 runtests: PYTHONHASHSEED='2156646470' + py27 runtests: commands[0] | /../sprockets.http/build/tox/py27/bin/nosetests + py34 inst: /../sprockets.http/.build/tox/dist/sprockets.http-0.0.0.zip + py34 runtests: PYTHONHASHSEED='2156646470' + py34 runtests: commands[0] | /.../sprockets.http/build/tox/py34/bin/nosetests + _________________________________ summary _________________________________ + py27: commands succeeded + py34: commands succeeded + congratulations :) + +This is what you want to see. Now you can make your modifications and keep +the tests passing. + +Submitting a Pull Request +------------------------- +Once you have made your modifications, gotten all of the tests to pass, +and added any necessary documentation, it is time to contribute back for +posterity. You've probably already cloned this repository and created a +new branch. If you haven't, then checkout what you have as a branch and +roll back *master* to where you found it. Then push your repository up +to github and issue a pull request. Describe your changes in the request, +if Travis isn't too annoyed someone will review it, and eventually merge +it back. + +.. _flake8: http://flake8.readthedocs.org/ +.. _nose: http://nose.readthedocs.org/ +.. _sphinx: http://sphinx-doc.org/ +.. _detox: http://testrun.org/tox/ +.. _tox: http://testrun.org/tox/ +.. _virtualenv: http://virtualenv.pypa.io/ diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 0000000..baa4313 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1,7 @@ +.. :changelog: + +Release History +=============== + +Next Release +------------ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..aefcb22 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,7 @@ +.. include:: ../README.rst + +.. toctree:: + :hidden: + + contributing + history diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..5812ca4 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,2 @@ +[build_sphinx] +all-files = 1