Merge pull request #5460 from benjaoming/docs-toc-level

Docs TOC level and installation instruction improvements

docs/installguide/advanced.rst

@@ -1,56 +1,54 @@
 .. _advanced-installation:
 
-Advanced installation options
-=============================
+Other options
+=============
 
 .. note::
-    Every time you install or update kalite, you should (re)run
-    ``kalite manage setup`` to setup the database and download content packs
-    (exercise texts, images, translations etc.).
+    Every time you update kalite, you should (re)run ``kalite manage setup`` to
+    ensure that the database and contents are kept updated.
 
 
 .. _pip-installation:
 
-Generic installation (pip install)
-__________________________________
+Generic installation ``pip install``
+____________________________________
 
+You can install KA Lite from the online Python Package Index (PyPi) using its
+package system `pip`.
 
-Installing through pip or with setup.py
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note:: PyPi sources do not contain content and exercise data, so you need to
+  :url-pantry:`download the contentpack en.zip manually <content/contentpacks/en.zip>` (>700 MB).
 
-For command line users with access to pip, you can install KA Lite from an
-online source like this::
+If you are installing system-wide, it's preferable to use ``ka-lite-static`` which
+has dependencies bundled in and doesn't interfere with your system's setup::
 
-    pip install ka-lite
-
-
-Static version
-~~~~~~~~~~~~~~
+    sudo pip install ka-lite-static
 
-If you need to run KA Lite with static dependencies bundled and isolated from
-the rest of your environment, you can run::
+You can also install KA Lite in a virtual environment or on the current user's
+local python packages without dependencies bundled in::
 
-    pip install ka-lite-static
+    pip install ka-lite
 
 
 Portable tarballs / zip files with setup.py
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you can't install KA Lite on systems with the standard Windows/Mac/Linux installers,
-you can fetch the KA Lite python package from `PyPi <https://pypi.python.org/pypi/ka-lite-static>`_.
+If you can't install KA Lite on systems with the standard
+Windows/Mac/Linux installers, you can fetch the KA Lite python package from
+`PyPi <https://pypi.python.org/pypi/ka-lite-static>`_.
 
-To unpack the package for installation, run:
+To unpack the package for installation on Linux/Mac, run:
 
 .. parsed-literal::
 
    tar -xf ka-lite-static-|release|.tar.gz
 
-Once it's unpacked, install it by entering the extracted directory and running::
+Once it's unpacked, install it by entering the extracted directory and running:
 
-    sudo python setup.py install
+.. parsed-literal::
 
-Beware that the PyPi sources do not contain assessment items, so you need to
-:url-pantry:`download the contentpack en.zip manually <content/contentpacks/en.zip>` (>700 MB)..
+    cd ka-lite-static-|release|
+    sudo python setup.py install
 
 
 .. _ppa-installation:
@@ -73,14 +71,24 @@ To add the PPA as a repository on an apt-based system, you need to ensure that a
 
 .. _gtk-installation:
 
-User interface for Debian/Ubuntu
-__________________________________
+User interface for Linux/GTK
+____________________________
+
+A Control Panel for simple start/stop functionality and a bit of user setup is
+available with a user interface. It's not feature-complete, but good enough for simple
+usage.
 
-Make sure you have the PPA added, then run::
+Make sure you have the PPA added (see :ref:`ppa-installation`), then run::
 
     sudo apt-get install ka-lite-gtk
 
 
+On non-Debian systems, you can install the GTK interface with Pip::
+  
+    sudo pip install ka-lite-gtk  # Install
+    ka-lite-gtk  # Launch the KA Lite UI
+
+
 .. _development-installation:
 
 Development

docs/installguide/install_all.rst

@@ -1,6 +1,9 @@
 Windows
 =======
 
+Installation
+____________
+
 #. Download the KA Lite :url-windows-installer:`Windows installer <>` v. |release|.
 #. Double-click the downloaded .exe file, and the wizard window will appear to guide you through the process of installing KA Lite on your server.
 
@@ -72,8 +75,8 @@ See the :doc:`release notes <release_notes>` for critical upgrade information fo
 Linux
 =====
 
-Main method: Ubuntu/Debian .deb
-_______________________________
+Ubuntu/Debian .deb
+__________________
 
 Download the :url-deb-installer:`latest .deb <>` installer v. |release|, and run this command::
 
@@ -118,6 +121,13 @@ process. Generally the default value is ok.
     If you want to receive automatic updates from online sources, you can
     also use :ref:`ppa-installation`.
 
+Upgrade
+~~~~~~~
+
+To upgrade KA Lite on Linux, simply download the latest deb file and follow the instructions above for installation.
+Your existing data will be preserved by default.
+See the :doc:`release notes <release_notes>` for critical upgrade information for specific versions.
+
 
 .. _raspberry-pi-install:
 
@@ -146,21 +156,9 @@ run ``sudo apt-get install ka-lite-raspberry-pi``.
 For a more thorough guide, see :ref:`raspberry-pi-tutorial`.
 
 
-Other options
-_____________
+Other distributions
+___________________
 
 KA Lite is available for all platforms (e.g. non-Debian compatible platforms)
 through PyPi. See :ref:`pip-installation`.
 
-Upgrade
-_______
-
-To upgrade KA Lite on Linux, simply download the latest deb file and follow the instructions above for installation.
-Your existing data will be preserved by default.
-See the :doc:`release notes <release_notes>` for critical upgrade information for specific versions.
-
-Configuration after installation or update
-__________________________________________
-
-Every time you install or update KA Lite, you must run ``kalite manage setup`` command again to setup the database and download assessment items (video descriptions,
-exercises etc.).

docs/installguide/install_main.rst

@@ -1,13 +1,17 @@
 KA Lite Installation Guides
 ===========================
-Hello! If you know what OS you're installing on then click ahead.
+
+Installers for a number of platforms are available, each with separate
+installation steps. Click ahead for installation instructions, and if you're
+updating be sure to check out our release notes.
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 2
 
     Installation Guide <install_all>
-    Release Notes <release_notes>
     Advanced Installation <advanced>
     Raspberry Pi Tutorial <tutorial_rpi>
     System Requirements <system_requirements>
     Uninstalling <uninstall>
+    Release Notes <release_notes>
+