From 8511fec1f9a610b0b26547a1620ce034ad9d9947 Mon Sep 17 00:00:00 2001 From: Chris Laws Date: Sun, 8 May 2016 14:00:27 +0930 Subject: [PATCH] Add documentation; integrate sphinx --- .gitignore | 1 + Makefile | 9 ++- docs/_build/.gitignore | 0 docs/_static/.gitignore | 0 docs/_templates/.gitignore | 0 docs/api/index.rst | 17 +++++ docs/conf.py | 81 ++++++++++++++++++++++++ docs/dev/index.rst | 123 +++++++++++++++++++++++++++++++++++++ docs/index.rst | 63 +++++++++++++++++++ docs/user/index.rst | 40 ++++++++++++ requirements.dev.txt | 2 + uvloop/loop.pyx | 2 +- 12 files changed, 335 insertions(+), 3 deletions(-) create mode 100644 docs/_build/.gitignore create mode 100644 docs/_static/.gitignore create mode 100644 docs/_templates/.gitignore create mode 100644 docs/api/index.rst create mode 100644 docs/conf.py create mode 100644 docs/dev/index.rst create mode 100644 docs/index.rst create mode 100644 docs/user/index.rst create mode 100644 requirements.dev.txt diff --git a/.gitignore b/.gitignore index f0cd113..0a7b240 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,4 @@ __pycache__/ /*.egg-info /dist /.cache +docs/_build diff --git a/Makefile b/Makefile index 6bd41e9..7be7ded 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,12 @@ -.PHONY: compile clean all distclean test debug sdist clean-libuv release sdist-libuv +.PHONY: compile clean all distclean test debug sdist clean-libuv +.PHONY: release sdist-libuv docs all: clean compile clean: - rm -fr dist/ + rm -fr dist/ doc/_build/ rm -fr uvloop/*.c uvloop/*.html uvloop/*.so build *.egg-info rm -fr uvloop/handles/*.html uvloop/includes/*.html find . -name '__pycache__' | xargs rm -rf @@ -34,6 +35,10 @@ debug: clean python setup.py build_ext --inplace +docs: compile + cd docs && sphinx-build -b html . _build/html + + test: PYTHONASYNCIODEBUG=1 python -m unittest discover -s tests python -m unittest discover -s tests diff --git a/docs/_build/.gitignore b/docs/_build/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/docs/_templates/.gitignore b/docs/_templates/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..fef4df3 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,17 @@ +API +=== + +If you are looking for information on a specific function, class or method, +this part of the documentation is for you. + + +uvloop +------ + +.. autoclass:: uvloop.EventLoopPolicy + :members: + +.. autoclass:: uvloop.loop.Loop + :members: + :undoc-members: + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..6ef1455 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 + +import sys +import os + +import alabaster + + +sys.path.insert(0, os.path.abspath('..')) + + +# -- General configuration ------------------------------------------------ + +extensions = [ + 'sphinx.ext.autodoc', + 'alabaster', +] +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' +project = 'uvloop' +copyright = '2016, Yury Selivanov' +author = 'Yury Selivanov' +version = '0.4.14' +release = '0.4.14' +language = None +exclude_patterns = ['_build'] +pygments_style = 'sphinx' +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +html_theme = 'alabaster' +html_theme_options = { + 'description': 'uvloop is an ultra fast implementation of the ' + 'asyncio event loop on top of libuv.', + 'show_powered_by': False, +} +html_theme_path = [alabaster.get_path()] +html_title = 'uvloop Documentation' +html_short_title = 'uvloop' +html_static_path = ['_static'] +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'searchbox.html', + ] +} +html_show_sourcelink = False +html_show_sphinx = False +html_show_copyright = False +htmlhelp_basename = 'uvloopdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = {} + +latex_documents = [ + (master_doc, 'uvloop.tex', 'uvloop Documentation', + 'Yury Selivanov', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +man_pages = [ + (master_doc, 'uvloop', 'uvloop Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +texinfo_documents = [ + (master_doc, 'uvloop', 'uvloop Documentation', + author, 'uvloop', 'One line description of project.', + 'Miscellaneous'), +] diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 0000000..21bf05d --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,123 @@ +Developers Guide +================ + +The project is hosted on `GitHub `_. +and uses `Travis `_ for +Continuous Integration. + +A goal for the `uvloop` project is to provide a drop in replacement for the +`asyncio` event loop. Any deviation from the behavior of the reference +`asyncio` event loop is considered a bug. + +If you have found a bug or have an idea for an enhancement that would +improve the library, use the `bug tracker `_. + + +Get the source +-------------- + +.. code-block:: console + + $ git clone --recursive git@github.com:MagicStack/uvloop.git + +The ``--recursive`` argument is important. It will fetch the ``libuv`` source +from the `libuv` Github repository. + + +Build +----- + +To build `uvloop`, you'll need ``Cython`` and Python 3.5. + +.. note:: + + The best way to work on `uvloop` is to create a virtual env, so that + you'll have Cython and Python commands pointing to the correct + tools. + + .. code-block:: console + + $ python3 -m venv myvenv + $ cd myvenv + $ source bin/activate + $ cd .. + +Install Cython if not already present. + +.. code-block:: console + + $ pip install Cython + + +Build `uvloop` by running the ``make`` rule from the top level directory. + +.. code-block:: console + + $ cd uvloop + $ make + + +Test +---- + +The easiest method to run all of the unit tests is to run the ``make test`` +rule from the top level directory. This runs the standard library +``unittest`` tool which discovers all the unit tests and runs them. +It actually runs them twice, once with the `PYTHONASYNCIODEBUG` enabled and +once without. + +.. code-block:: console + + $ cd uvloop + $ make test + + +Individual Tests +++++++++++++++++ + +Individual unit tests can be run using the standard library ``unittest`` +or ``pytest`` package. + +The easiest approach to ensure that ``uvloop`` can be found by Python is to +install the package using ``pip``: + +.. code-block:: console + + $ cd uvloop + $ pip install -e . + +You can then run the unit tests individually from the tests directory using +``unittest``: + +.. code-block:: console + + $ cd uvloop/tests + $ python -m unittest test_tcp + +or using ``pytest``: + +.. code-block:: console + + $ cd uvloop/tests + $ py.test -k test_signals_sigint_uvcode + + +Documentation +------------- + +To rebuild the project documentation, developers should run the ``make docs`` +rule from the top level directory. It performs a number of steps to create +a new set of `sphinx `_ html content. + +This step requires Sphinx to be installed. Sphinx can be installed using +pip: + +.. code-block:: console + + $ pip install sphinx + +Once Sphinx is available you can make the documentation using: + +.. code-block:: console + + $ make docs diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..47ad57b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,63 @@ + +.. raw:: html + +
+ + +
+
+
+ +uvloop +====== + +`uvloop` is a fast, drop-in replacement of the built-in asyncio event loop. +`uvloop` is released under the MIT license. + +`uvloop` and asyncio, combined with the power of async/await in Python 3.5, +makes it easier than ever to write high-performance networking code in Python. + +`uvloop` makes asyncio fast. In fact, it is at least 2x faster than nodejs, +gevent, as well as any other Python asynchronous framework. The performance of +uvloop-based asyncio is close to that of Go programs. + +You can read more about uvloop in this `blog post `_. + +Architecture +------------ + +The asyncio module, introduced by PEP 3156, is a collection of network +transports, protocols, and streams abstractions, with a pluggable event loop. +The event loop is the heart of asyncio. It provides APIs for: + +- scheduling calls, +- transmitting data over the network, +- performing DNS queries, +- handling OS signals, +- convenient abstractions to create servers and connections, +- working with subprocesses asynchronously. + +`uvloop` implements the :class:`asyncio.AbstractEventLoop` interface which +means that it provides a drop-in replacement of the asyncio event loop. + +`uvloop` is written in Cython and is built on top of libuv. + +libuv is a high performance, multiplatform asynchronous I/O library used by +nodejs. Because of how wide-spread and popular nodejs is, libuv is fast and +stable. + +`uvloop` implements all asyncio event loop APIs. High-level Python objects +wrap low-level libuv structs and functions. Inheritance is used to keep the +code DRY and ensure that any manual memory management is in sync with libuv +primitives' lifespans. + + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + user/index + dev/index + api/index diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 0000000..8cebfe6 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,40 @@ +User Guide +========== + +This section of the documentation provides information about how to use +uvloop. + + +Installation +------------ + +`uvloop` is available from PyPI. It requires Python 3.5. + +Use pip to install it. + +.. code-block:: console + + $ pip install uvloop + + +Using uvloop +------------ + +To make asyncio use the event loop provided by `uvloop`, you install the +`uvloop` event loop policy: + +.. code-block:: python + + import asyncio + import uvloop + asyncio.set_event_loop_policy(uvloop.EventLoopPolicy()) + + +Alternatively, you can create an instance of the loop manually, using: + +.. code-block:: python + + import asyncio + import uvloop + loop = uvloop.new_event_loop() + asyncio.set_event_loop(loop) diff --git a/requirements.dev.txt b/requirements.dev.txt new file mode 100644 index 0000000..a5e9c61 --- /dev/null +++ b/requirements.dev.txt @@ -0,0 +1,2 @@ +Cython>=0.24 +Sphinx>=1.4.1 diff --git a/uvloop/loop.pyx b/uvloop/loop.pyx index c882c84..f65423e 100644 --- a/uvloop/loop.pyx +++ b/uvloop/loop.pyx @@ -1,4 +1,4 @@ -# cython: language_level=3 +# cython: language_level=3, embedsignature=True include "__debug.pxi" # Generated by "make"