Merge pull request #86 from willingc/sphinx-update

Update index of Sphinx docs

docs/source/changelog.rst

@@ -1,7 +1,7 @@
 .. _changelog:
 
-Changes in Jupyter QtConsole
-============================
+Changes in Jupyter Qt console
+=============================
 
 .. _4.1:
 
@@ -45,4 +45,4 @@ Changes in Jupyter QtConsole
 
 `4.0 on GitHub <https://github.com/jupyter/qtconsole/milestones/4.0>`__
 
-First release of qtconsole as a standalone package.
+First release of the Qt console as a standalone package.

docs/source/conf.py

@@ -138,7 +138,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/index.rst

@@ -1,27 +1,29 @@
 .. _qtconsole:
 
-========================
-A Qt Console for Jupyter
-========================
+==========================
+The Qt Console for Jupyter
+==========================
 
 :Release: |release|
 :Date: |today|
 
 To start the Qt console::
 
-    $> jupyter qtconsole
+    $ jupyter qtconsole
 
 .. toctree::
    :maxdepth: 2
 
+   installation
    config_options
    changelog
 
-You can use any Jupyter kernel with this PyQt_ console GUI.
-This is a very lightweight widget that
-largely feels like a terminal, but provides a number of enhancements only
-possible in a GUI, such as inline figures, proper multiline editing with syntax
-highlighting, graphical calltips, and much more.
+Overview
+========
+The Qt console is a very lightweight application that largely feels like a
+terminal, but provides a number of enhancements only possible in a GUI, such as
+inline figures, proper multiline editing with syntax highlighting, graphical
+calltips, and much more. The Qt console can use any Jupyter kernel.
 
 .. figure:: _images/qtconsole.png
     :width: 400px
@@ -31,8 +33,8 @@ highlighting, graphical calltips, and much more.
 
     The Qt console with IPython, using inline matplotlib plots.
 
-The Qt frontend has hand-coded emacs-style bindings for text navigation. This
-is not yet configurable.
+The Qt console frontend has hand-coded emacs-style bindings for text
+navigation. This is not yet configurable.
 
 .. tip::
 
@@ -43,43 +45,11 @@ is not yet configurable.
    point in a multiline block, you can force its execution (without having to
    go to the bottom) with :kbd:`Shift-Enter`.
 
-Installation
-============
-
-.. seealso::
-
-   `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`__
-     The Qt console is part of the Jupyter ecosystem.
-
-You can install the Qt console with::
-
-    pip install qtconsole
-    # OR
-    conda install qtconsole
-
-If you're new to Python, we recommend installing `Anaconda <http://continuum.io/downloads#py34>`__,
-a Python distribution which includes the Qt console and the other Jupyter components.
-
-Qt
---
-
-The Qt console requires `PyQt <http://www.riverbankcomputing.com/software/pyqt/intro>`__
-or `PySide <http://pyside.github.io/docs/pyside/>`__, which can't be installed
-with pip.
-
-If you install the Qt console using conda, it will automatically install PyQt
-as well.
-
-Otherwise, you can `download PyQt manually <http://www.riverbankcomputing.com/software/pyqt/download5>`__,
-or install it using your system package manager, e.g.::
-
-    sudo apt-get install python3-pyqt5
-
 
 Inline graphics
 ===============
 
-One of the most exciting features of the QtConsole is embedded figures.
+One of the most exciting features of the Qt Console is embedded figures.
 You can plot with matplotlib in IPython, or the plotting library of choice
 in your kernel.
 
@@ -92,24 +62,24 @@ in your kernel.
 Saving and Printing
 ===================
 
-QtConsole has the ability to save your current session, as either HTML or
-XHTML. Your inlinke figures
-will be PNG in HTML, or inlined as SVG in XHTML. PNG images have the option to
-be either in an external folder, as in many browsers' "Webpage, Complete"
-option, or inlined as well, for a larger, but more portable file.
+The Qt Console has the ability to save your current session, as either HTML or
+XHTML. Your inline figures will be PNG in HTML, or inlined as SVG in XHTML.
+PNG images have the option to be either in an external folder, as in many
+browsers' "Webpage, Complete" option, or inlined as well, for a larger, but
+more portable file.
 
 .. note::
 
     Export to SVG+XHTML requires that you are using SVG figures, which is *not*
     the default.  To switch the inline figure format in IPython to use SVG, do:
-    
+
     .. sourcecode:: ipython
-    
+
         In [10]: %config InlineBackend.figure_format = 'svg'
-    
+
     Or, you can add the same line (c.Inline... instead of %config Inline...) to
     your config files.
-    
+
     This will only affect figures plotted after making this call
 
 
@@ -144,7 +114,7 @@ theme:
 
 .. image:: figs/colors_dark.png
     :width: 627px
-    
+
 .. Note::
 
     Calling ``jupyter qtconsole -h`` will show all the style names that
@@ -170,7 +140,7 @@ stylesheet:
 Fonts
 =====
 
-The QtConsole has configurable via the ConsoleWidget. To change these, set the
+The Qt console is configurable via the ConsoleWidget. To change these, set the
 ``font_family`` or ``font_size`` traits of the ConsoleWidget. For instance, to
 use 9pt Anonymous Pro::
 
@@ -405,10 +375,10 @@ Rules:
       the Kernel has been shutdown.
     * Remote Consoles may not restart or shutdown the kernel.
 
-Qt and the QtConsole
+Qt and the Qt console
 ====================
 
-An important part of working with the QtConsole when you are writing your own
+An important part of working with the Qt console when you are writing your own
 Qt code is to remember that user code (in the kernel) is *not* in the same
 process as the frontend.  This means that there is not necessarily any Qt code
 running in the kernel, and under most normal circumstances there isn't.
@@ -421,7 +391,7 @@ Python reference to them, so you have to hold on to them.  For instance, in:
 
     def make_window():
         win = QtGui.QMainWindow()
-    
+
     def make_and_return_window():
         win = QtGui.QMainWindow()
         return win
@@ -433,7 +403,7 @@ you know that you always want your objects to last as long as the process, you
 can attach them to the QApplication instance itself:
 
 .. sourcecode:: python
-    
+
     # do this just once:
     app = QtCore.QCoreApplication.instance()
     app.references = set()

docs/source/installation.rst

@@ -0,0 +1,54 @@
+Installation
+============
+The Qt console requires Qt, such as
+`PyQt5 <http://www.riverbankcomputing.com/software/pyqt/intro>`_,
+`PyQt4 <https://www.riverbankcomputing.com/software/pyqt/download>`_, or
+`PySide <http://pyside.github.io/docs/pyside>`_.
+
+Although `pip <https://pypi.python.org/pypi/pip>`_ and
+`conda <http://conda.pydata.org/docs>`_ may be used to install the Qt console,
+conda is simpler to use since it automatically installs PyQt. Alternatively,
+qtconsole installation with pip needs additional steps since pip cannot install
+the Qt requirement.
+
+Install using conda
+-------------------
+To install::
+
+    conda install qtconsole
+
+.. note::
+
+    If the Qt console is installed using conda, it will **automatically**
+    install the Qt requirement as well.
+
+Install using pip
+-----------------
+To install::
+
+    pip install qtconsole
+
+.. important::
+
+    Make sure that Qt is installed. Unfortunately, Qt cannot be
+    installed using pip. The next section gives instructions on installing Qt.
+
+Installing Qt (if needed)
+-------------------------
+We recommend installing PyQt with `conda <http://conda.pydata.org/docs>`_::
+
+    conda install pyqt
+
+or with a system package manager. For Windows, PyQt binary packages may be
+used.
+
+For example with Linux Debian's system package manager, use::
+
+   sudo apt-get install python3-pyqt5 # PyQt5 on Python 3
+   sudo apt-get install python3-pyqt4 # PyQt4 on Python 3
+   sudo apt-get install python-qt4    # PyQt4 on Python 2
+
+.. seealso::
+
+   `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`_
+   The Qt console is part of the Jupyter ecosystem.