Restructured documentation -- now we have a tutorial! not a very help…

…ful one though
selectel · Jul 6, 2011 · 4294eb1 · 4294eb1
1 parent 758da06
commit 4294eb1
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 63 deletions.
diff --git a/README b/README
@@ -45,63 +45,8 @@ you can use ``easy_install -U pyte``. Otherwise, you can download the source
 from `GitHub <http://github.com/selectel/pyte>`_ and run ``python setup.py install``.
 
 
-Quick example
--------------
-
-There are two important classes in ``pyte``: ``Screen`` and ``Stream``. The
-``Screen`` is the terminal screen emulator. It maintains an in-memory
-buffer of text and text-attributes to display on screen. The ``Stream``
-is the stream processor. It manages the state of the input and dispatches
-events to anything that's listening about things that are going on.
-Events are things like ``LINEFEED``, ``DRAW "a"``, or ``CURSOR_POSITION 10 10``.
-See the `API documentation` for more details.
-
-In general, if you just want to know what's being displayed on screen you
-can do something like the following:
-
-    >>> import pyte
-    >>> screen = pyte.Screen(80, 24)
-    >>> stream = pyte.Stream()
-    >>> stream.attach(screen)
-    >>> stream.feed("Hello World!")
-    >>> screen.display
-        ['Hello World!                                                                    ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ',
-         '                                                                                ']
-
-
-**Note**: ``Screen`` has no idea what is the source of bytes, fed into ``Stream``,
-so, obviously, it **can't read** or **change** environment variables, which implies
-that:
-
-* it doesn't adjust `LINES` and `COLUMNS` on ``"resize"`` event;
-* it doesn't use locale settings (`LC_*` and `LANG`);
-* it doesn't use `TERM` value and expects it to be `"linux"` and only `"linux"`.
-
-
-Alternatives
-------------
+Similar projects
+----------------
 
 ``pyte`` is not alone in the weird world of terminal emulator libraries,
 here's a few other options worth checking out:

diff --git a/docs/api.rst b/docs/api.rst
@@ -1,8 +1,8 @@
 .. _api:
 
 
-API
-===
+API reference
+=============
 
 .. automodule:: pyte
 

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../CHANGES
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,9 +6,29 @@
 .. include:: ../README
 
 
-More ...
---------
+``pyte`` users
+--------------
 
-Unfortunately, ``pyte`` doesn't have anything but the :ref:`API  documentation <api>`
-at the moment.
+Believe it or not, there're project which actually **need** a terminal emulator
+library, not many of them use ``pyte`` though:
+
+* `Selectel <http://selectel.com>`_ -- hey, we wrote this thing :)
+* `Ajenti <http://github.com/Eugeny/ajenti>`_ -- easy to use weadmin panel for Linux
+  and BSD uses ``pyte`` for its terminal plugin.
+
+
+Show me the code!
+-----------------
+
+Head over to our brief :ref:`tutorial` or, if you're feeling brave, dive right
+into the :ref:`api` -- ``pyte`` also has a couple of
+minimal examples in the ``examples/`` directory.
+
+
+.. toctree::
+   :hidden:
+
+   tutorial
+   api
+   changelog
 
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -0,0 +1,56 @@
+.. _tutorial:
+
+Tutorial
+--------
+
+There are two important classes in ``pyte``: :class:`~pyte.screens.Screen`
+and :class:`~pyte.streams.Stream`. The `Screen` is the terminal screen
+emulator. It maintains an in-memory buffer of text and text-attributes
+to display on screen. The `Stream` is the stream processor. It manages
+the state of the input and dispatches events to anything that's listening
+about things that are going on. Events are things like ``LINEFEED``,
+``DRAW "a"``, or ``CURSOR_POSITION 10 10``. See the :ref:`API reference <api>`
+for more details.
+
+In general, if you just want to know what's being displayed on screen you
+can do something like the following:
+
+    >>> import pyte
+    >>> screen = pyte.Screen(80, 24)
+    >>> stream = pyte.Stream()
+    >>> stream.attach(screen)
+    >>> stream.feed("Hello World!")
+    >>> screen.display
+        ['Hello World!                                                                    ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ',
+         '                                                                                ']
+
+
+**Note**: ``Screen`` has no idea what is the source of bytes, fed into ``Stream``,
+so, obviously, it **can't read** or **change** environment variables, which implies
+that:
+
+* it doesn't adjust `LINES` and `COLUMNS` on ``"resize"`` event;
+* it doesn't use locale settings (`LC_*` and `LANG`);
+* it doesn't use `TERM` value and expects it to be `"linux"` and only `"linux"`.