Improving the documentation.

docs/index.rst

@@ -1,13 +1,15 @@
 Python Prompt Toolkit
 =====================
 
-`prompt_toolkit` is a library for building powerful interactive command lines
+`prompt_toolkit` is a library for building powerful interactive command line
 and terminal applications in Python.
 
 
-It can be a pure Python replacement for `GNU readline
-<http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html>`_, but it can be much
-more than that.
+It can be a very advanced pure Python replacement for `GNU readline
+<http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html>`_, but it can also be
+used for building full screen applications.
+
+.. image:: images/ptpython.png
 
 Some features:
 
@@ -34,73 +36,18 @@ Works everywhere:
   also run in a telnet/ssh server or an `asyncio
   <https://docs.python.org/3/library/asyncio.html>`_ process.
 
-
-Two use cases: prompts versus full screen terminal applications
----------------------------------------------------------------
-
-``prompt_toolkit`` was in the first place meant to be a replacement for
-readline. However, when it became more mature, we realised that all the
-components for full screen applications are there and ``prompt_toolkit`` is
-very capable of handling many use cases. `Pyvim
-<http://github.com/jonathanslenders/pyvim>`_ and `pymux
-<http://github.com/jonathanslenders/pymux>`_ are examples of full screen
-applications.
-
-.. image:: images/pyvim.png
-
-Basically, at the core, ``prompt_toolkit`` has a layout engine, that supports
-horizontal and vertical splits as well as floats, where each "window" can
-display a user control. The API for user controls is simple yet powerful.
-
-When ``prompt_toolkit`` is used to simply read some input from the user, it
-uses a rather simple built-in layout. One that displays the default input
-buffer and the prompt, a float for the autocompletions and a toolbar for input
-validation which is hidden by default.
-
-For full screen applications, usually we build the layout ourself, because it's
-very custom.
-
-Further, there is a very flexible key binding system that can be programmed for
-all the needs of full screen applications.
-
-
-Installation
-------------
-
-::
-
-    pip install prompt_toolkit
-
-For Conda, do:
-
-::
-
-    conda install -c https://conda.anaconda.org/conda-forge prompt_toolkit
-
+Have a look at :ref:`the gallery <gallery>` to get an idea of what is possible.
 
 Getting started
 ---------------
 
-The following snippet is the most simple example, it uses the
-:func:`~prompt_toolkit.prompt` function to asks the user for input
-and returns the text. Just like ``(raw_)input``.
-
-.. code:: python
-
-    from __future__ import unicode_literals
-    from prompt_toolkit import prompt
-
-    text = prompt('Give me some input: ')
-    print('You said: %s' % text)
-
-For more information, start reading the :ref:`building prompts
-<building_prompts>` section.
+Go to :ref:`getting started <getting_started>` and build your first prompt.
 
 
 Thanks to:
 ----------
 
-Thanks to `all the contributors
+A special thanks to `all the contributors
 <https://github.com/jonathanslenders/python-prompt-toolkit/graphs/contributors>`_
 for making prompt_toolkit possible.
 
@@ -115,8 +62,9 @@ Table of contents
    :maxdepth: 3
 
    pages/gallery
+   pages/getting_started
    pages/printing_text
-   pages/building_prompts
+   pages/asking_for_input
    pages/dialogs
    pages/full_screen_apps
    pages/architecture

docs/pages/building_prompts.rst → docs/pages/asking_for_input.rst

@@ -1,4 +1,4 @@
-.. _building_prompts:
+.. _asking_for_input:
 
 Asking for input (prompts)
 ==========================
@@ -32,8 +32,8 @@ In the following sections, we will discover all these parameters.
 
 .. note::
 
-    ``prompt_toolkit`` expects unicode strings everywhere. If you are using
-    Python 2, make sure that all strings which are passed to ``prompt_toolkit``
+    `prompt_toolkit` expects unicode strings everywhere. If you are using
+    Python 2, make sure that all strings which are passed to `prompt_toolkit`
     are unicode strings (and not bytes). Either use 
     ``from __future__ import unicode_literals`` or explicitely put a small 
     ``'u'`` in front of every string.
@@ -65,8 +65,8 @@ Colors
 ------
 
 The colors for syntax highlighting are defined by a
-:class:`~prompt_toolkit.styles.Style` instance.  By default, a neutral built-in
-style is used, but any style instance can be passed to the
+:class:`~prompt_toolkit.styles.Style` instance. By default, a neutral
+built-in style is used, but any style instance can be passed to the
 :func:`~prompt_toolkit.shortcuts.prompt` function. A simple way to create a
 style, is by using the :meth:`~prompt_toolkit.styles.Style.from_dict`
 function:
@@ -90,9 +90,9 @@ function:
 The style dictionary is very similar to the Pygments ``styles`` dictionary,
 with a few differences:
 
-- The `roman`, `sans`, `mono` and `border` options are not ignored.
-- The style has a few additions: `blink`, `noblink`, `reverse` and `noreverse`.
-- Colors can be in the `#ff0000` format, but they can be one of the built-in
+- The `roman`, `sans`, `mono` and `border` options are ignored.
+- The style has a few additions: ``blink``, ``noblink``, ``reverse`` and ``noreverse``.
+- Colors can be in the ``#ff0000`` format, but they can be one of the built-in
   ANSI color names as well. In that case, they map directly to the 16 color
   palette of the terminal.
 
@@ -167,7 +167,7 @@ a list of ``(style, text)`` tuples.
 
 By default, colors are taking from the 256 color palette. If you want to have
 24bit true color, this is possible by adding the ``true_color=True`` option to
-the ``prompt`` function.
+the :func:`~prompt_toolkit.shortcuts.prompt.prompt`` function.
 
 .. code:: python
 

docs/pages/dialogs.rst

@@ -1,4 +1,4 @@
-.. _building_prompts:
+.. _dialogs:
 
 Dialogs
 =======

docs/pages/getting_started.rst

@@ -0,0 +1,82 @@
+.. _getting_started:
+
+Getting started
+===============
+
+Installation
+------------
+
+::
+
+    pip install prompt_toolkit
+
+For Conda, do:
+
+::
+
+    conda install -c https://conda.anaconda.org/conda-forge prompt_toolkit
+
+
+Several use cases: prompts versus full screen terminal applications
+--------------------------------------------------------------------
+
+`prompt_toolkit` was in the first place meant to be a replacement for readline.
+However, when it became more mature, we realised that all the components for
+full screen applications are there and `prompt_toolkit` is very capable of
+handling many use situations. `Pyvim
+<http://github.com/jonathanslenders/pyvim>`_ and `pymux
+<http://github.com/jonathanslenders/pymux>`_ are examples of full screen
+applications.
+
+.. image:: ../images/pyvim.png
+
+Basically, at the core, `prompt_toolkit` has a layout engine, that supports
+horizontal and vertical splits as well as floats, where each "window" can
+display a user control. The API for user controls is simple yet powerful.
+
+When `prompt_toolkit` is used to simply read some input from the user, it uses
+a rather simple built-in layout. One that displays the default input buffer and
+the prompt, a float for the autocompletions and a toolbar for input validation
+which is hidden by default.
+
+For full screen applications, usually we build the layout ourself, because
+that's very custom.
+
+Further, there is a very flexible key binding system that can be programmed for
+all the needs of full screen applications.
+
+A simple prompt
+---------------
+
+The following snippet is the most simple example, it uses the
+:func:`~prompt_toolkit.shortcuts.prompt` function to asks the user for input
+and returns the text. Just like ``(raw_)input``.
+
+.. code:: python
+
+    from __future__ import unicode_literals
+    from prompt_toolkit import prompt
+
+    text = prompt('Give me some input: ')
+    print('You said: %s' % text)
+
+
+Learning `prompt_toolkit`
+-------------------------
+
+In order to learn and understand `prompt_toolkit`, it is best to go through the
+all sections in the order below. Also don't forget to have a look at all the
+examples `examples
+<https://github.com/jonathanslenders/python-prompt-toolkit/tree/master/examples>`_
+in the repository.
+
+- First, :ref:`learn how to print text <printing_text>`. This is important,
+  because it covers how to use "formatted text", which is something you'll use
+  whenever you want to use colors anywhere.
+
+- Secondly, go through the :ref:`asking for input <asking_for_input>` section.
+  This is useful for almost any use case, even for full screen applications.
+
+- Then, learn about :ref:`dialogs`, which is easy and fun.
+
+- Finally, learn about :ref:`full_screen_applications`.

docs/pages/printing_text.rst

@@ -35,8 +35,9 @@ Formatted text
 
 There are three ways to print colors:
 
-- By creating an HTML object.
-- By creating an ANSI object that contains ANSI escape sequences.
+- By creating an :class:`~prompt_toolkit.formatted_text.HTML` object.
+- By creating an :class:`~prompt_toolkit.formatted_text.ANSI` object that
+  contains ANSI escape sequences.
 - By creating a list of ``(style, text)`` tuples.
 
 An instance of any of these three kinds of objects is called "formatted text".
@@ -46,9 +47,9 @@ There are various places in prompt toolkit, where we accept not just plain text
 HTML
 ^^^^
 
-``prompt_toolkit.HTML`` can be used to indicate that a string contains
-HTML-like formatting. It supports the basic tags for bold, italic and
-underline: ``<b>``, ``<i>`` and ``<u>``.
+:class:`~prompt_toolkit.formatted_text.HTML` can be used to indicate that a
+string contains HTML-like formatting. It supports the basic tags for bold,
+italic and underline: ``<b>``, ``<i>`` and ``<u>``.
 
 .. code:: python
 
@@ -104,7 +105,8 @@ ANSI
 Some people like to use the VT100 ANSI escape squences to generate output.
 Natively, this is however only supported on VT100 terminals, but prompt_toolkit
 can parse these, and map them to a formatted text instances. This means that they
-will work on Windows as well.
+will work on Windows as well. The :class:`~prompt_toolkit.formatted.ANSI` class
+takes care of that.
 
 .. code:: python
 
@@ -117,10 +119,11 @@ will work on Windows as well.
 Style/text tuples
 ^^^^^^^^^^^^^^^^^
 
-Internally, both `HTML` and `ANSI` objects are mapped to a list of ``(style,
-text)`` tuples. It is however also possible to create such a list manually.
-This is a little more verbose, but it's probably the most powerful way of
-expressing formatted text.
+Internally, both :class:`~prompt_toolkit.formatted_text.HTML` and
+:class:`~prompt_toolkit.formatted_text.ANSI` objects are mapped to a list of
+``(style, text)`` tuples. It is however also possible to create such a list
+manually.  This is a little more verbose, but it's probably the most powerful
+way of expressing formatted text.
 
 .. code:: python
 
@@ -136,21 +139,23 @@ expressing formatted text.
 
     print(text, style=style)
 
-Similar to the `HTML` example, it's also possible to use class names, and
-separate the styling in a style sheet.
+Similar to the :class:`~prompt_toolkit.formatted_text.HTML` example, it is also
+possible to use class names, and separate the styling in a style sheet.
 
 .. code:: python
 
     from __future__ import unicode_literals, print_function
     from prompt_toolkit import print
     from prompt_toolkit.styles import Style
 
+    # The text.
     text = [
         ('class:aaa', 'Hello'),
         ('', ' '),
         ('class:bbb', 'World'),
     ]
 
+    # The style sheet.
     style = Style.from_dict({
         'aaa': '#ff0066',
         'bbb': '#44ff00 italic',

docs/pages/reference.rst

@@ -7,6 +7,12 @@ Application
 .. automodule:: prompt_toolkit.application
     :members:
 
+Formatted text
+--------------
+
+.. automodule:: prompt_toolkit.formatted_text
+    :members:
+
 Buffer
 ------
 
@@ -70,7 +76,25 @@ Keys
 Style
 -----
 
-.. automodule:: prompt_toolkit.styles
+.. automodule:: prompt_toolkit.styles.base
+    :members:
+
+.. automodule:: prompt_toolkit.styles.style
+    :members:
+
+.. automodule:: prompt_toolkit.styles.defaults
+    :members:
+
+.. automodule:: prompt_toolkit.styles.from_dict
+    :members:
+
+.. automodule:: prompt_toolkit.styles.from_pygments
+    :members:
+
+.. automodule:: prompt_toolkit.styles.named_colors
+    :members:
+
+.. automodule:: prompt_toolkit.styles.utils
     :members:
 
 Reactive
@@ -82,7 +106,10 @@ Reactive
 Shortcuts
 ---------
 
-.. automodule:: prompt_toolkit.shortcuts
+.. automodule:: prompt_toolkit.shortcuts.prompt
+    :members:
+
+.. automodule:: prompt_toolkit.shortcuts.dialogs
     :members:
 
 Validation