Better documentation for hyperframe.

Lukasa · Lukasa · commit f1fe11be86b0 · 2015-10-12T14:58:29.000+01:00
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -0,0 +1,66 @@
+hyperframe API
+==============
+
+This document provides the hyperframe API.
+
+All frame classes are subclasses of :class:`Frame <hyperframe.frame.Frame>`,
+and provide the methods and attributes defined there. Additionally, some frames
+use the :class:`Priority <hyperframe.frame.Priority>` and
+:class:`Padding <hyperframe.frame.Padding>` mixins, and make the methods and
+attributes defined on *those* mixins available as well.
+
+Rather than clutter up the documentation repeatedly documenting those methods
+and objects, we explicitly show the inheritance heirarchy of the frames: don't
+forget to consule the parent classes before deciding if a method or attribute
+you need is not present!
+
+.. autoclass:: hyperframe.frame.Frame
+   :members:
+
+.. autoclass:: hyperframe.frame.Padding
+   :members:
+
+.. autoclass:: hyperframe.frame.Priority
+   :members:
+
+.. autoclass:: hyperframe.frame.DataFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.PriorityFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.RstStreamFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.SettingsFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.PushPromiseFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.PingFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.GoAwayFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.WindowUpdateFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.HeadersFrame
+   :show-inheritance:
+   :members:
+
+.. autoclass:: hyperframe.frame.ContinuationFrame
+   :show-inheritance:
+   :members:
+
+.. autodata:: hyperframe.frame.FRAMES
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,22 +1,34 @@
-.. hyperframe documentation master file, created by
-   sphinx-quickstart on Mon Oct 12 14:06:36 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+hyperframe: HTTP/2 Framing for Python
+=====================================
 
-Welcome to hyperframe's documentation!
-======================================
+hyperframe is a pure-Python tool for working with HTTP/2 frames. This library
+allows you to create, serialize, and parse HTTP/2 frames.
 
-Contents:
+Working with it is easy:
 
-.. toctree::
-   :maxdepth: 2
+.. code-block:: python
+
+    import hyperframe
+
+    f = hyperframe.frame.DataFrame(stream_id=5)
+    f.data = b'some binary data'
+    f.flags.add('END_STREAM')
+    f.flags.add('PADDED')
+    f.padding_length = 30
 
+    data = f.serialize()
 
+    new_frame = hyperframe.frame.Frame.parse_frame_header(data[:9])
+    new_frame.parse_body(data[9:])
 
-Indices and tables
-==================
+hyperframe is pure-Python, contains no external dependencies, and runs on a
+wide variety of Python interpreters and platforms. Made available under the MIT
+license, why write your own frame parser?
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Contents:
+
+.. toctree::
+   :maxdepth: 2
 
+   installation
+   api
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -0,0 +1,21 @@
+Installing hyperframe
+=====================
+
+hyperframe is trivial to install from the Python Package Index. Simply run:
+
+.. code-block:: console
+
+    $ pip install hyperframe
+
+Alternatively, feel free to download one of the release tarballs from
+`our GitHub page`_, extract it to your favourite directory, and then run
+
+.. code-block:: console
+
+    $ python setup.py install
+
+hyperframe has no external dependencies.
+
+
+
+.. _our GitHub page: https://github.com/python-hyper/hyperframe
diff --git a/hyperframe/frame.py b/hyperframe/frame.py
