Add documentation; integrate sphinx

.gitignore

@@ -26,3 +26,4 @@ __pycache__/
 /*.egg-info
 /dist
 /.cache
+docs/_build

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

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:
+

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'),
+]

docs/dev/index.rst

@@ -0,0 +1,123 @@
+Developers Guide
+================
+
+The project is hosted on `GitHub <https://github.com/MagicStack/uvloop>`_.
+and uses `Travis <https://travis-ci.org/MagicStack/uvloop>`_ 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 <https://github.com/MagicStack/uvloop/issues>`_.
+
+
+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 <http://sphinx-doc.org/>`_ 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

docs/index.rst

@@ -0,0 +1,63 @@
+
+.. raw:: html
+
+    <div>
+        <img src="https://img.shields.io/pypi/status/uvloop.svg?maxAge=2592000?style=plastic" />
+        <img src="https://img.shields.io/travis/MagicStack/uvloop/master.svg" />
+        <br />
+        <br />
+    </div>
+
+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 <http://magic.io/blog/uvloop-blazing-fast-python-networking/>`_.
+
+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

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)

requirements.dev.txt

@@ -0,0 +1,2 @@
+Cython>=0.24
+Sphinx>=1.4.1

uvloop/loop.pyx

@@ -1,4 +1,4 @@
-# cython: language_level=3
+# cython: language_level=3, embedsignature=True
 
 
 include "__debug.pxi" # Generated by "make"