Merge pull request #5380 from benjaoming/content-pack-releasenotes

Documentation updates for 0.17

circle.yml

@@ -20,7 +20,7 @@ test:
     - make assets
     - make docs
     - kalite start --traceback -v2
-    - sleep 2s  # Necessary for server to be ready
+    - sleep 4s  # Necessary for server to be ready
     - kalite status
     - kalite stop --traceback -v2
     - case $CIRCLE_NODE_INDEX in 0) coverage run --source=kalite --omit="kalite/testing/*,*/tests/*,*/migrations/*,kalite/packages/*" bin/kalite manage test --bdd-only ;; 1) coverage run --source=kalite --omit="kalite/testing/*,kalite/packages/*,*/tests/*,*/migrations/*" bin/kalite manage test --no-bdd;; esac:

docs/developer_docs/documentation.rst

@@ -25,8 +25,59 @@ Documentation development
    be started. To build the docs::
    
        pip install -r requirements_sphinx.txt  # To install software for building docs
-       cd docs
-       make html
+       make docs
 
 #. You can view the docs in a browser by opening *docs/_build/html/index.html*.
 #. After you are satisfied with your changes push them to your fork of the ka-lite project, and then open a PR.
+
+Screenshots
+-----------
+
+Screenshots are made automatically following the screenshots directives. They are stored in a folder ``docs/_static/``, which is also sync’ed to Github.
+
+To grab new screenshots, you have to have Firefox installed and run::
+
+    cd docs/
+    SPHINX_SS_USE_PVD=true make SPHINXOPTS="-D screenshots_create=1" html
+
+Usage of screenshot Sphinx directive
+____________________________________
+
+Example code::
+
+    .. screenshot::
+      :navigation-steps: LOGIN admin superpassword
+      :focus: #id_username | Enter your username and password using this form!
+      :class: screenshot
+
+
+.. warning:: Read the following, but then read :ref:`thing-about-click` before using the screenshot directive.
+
+A screenshot directive has a number of required options:
+
+ * ``:user-role:`` which can be one of ``guest``, ``learner``, ``coach``, or ``admin``, and determines what kind of user is logged in for the screenshot.
+ * ``:url:`` which is the relative URL to take the screenshot at (or start a sequence of navigation actions to get to the page to take the screenshot at). Don't use urls with UUIDs, as those are dependent on the database and we can't guarantee what will be in the database for screenshot purposes.
+ * ``:navigation-steps:`` which is a sequence of steps that needs to be taken.
+   See the docstring of _parse_nav_steps in screenshot.py file for specification.
+   If you find yourself writing the same sequence of nav steps over and over again, possibly with minor variations, then we can write an alias for it as for LOGIN.
+ * ``:focus:`` which will highlight an element specified by jQuery-style selector (by giving it a nice red border) and optionally add a floating annotation box. Works like this:
+    :focus: the_selector | A nice little message that follows.
+
+Just use arbitrary selection a la jQuery (so put a hash in front of IDs, etc). Whitespace can be included, e.g. ``li a.classname``. Use the separator for annotations!
+
+
+.. _thing-about-click:
+
+The thing about ``click``
+_________________________
+
+The ``:navigation-steps:`` option is meant to simulate user interaction for screenshots. Unfortunately, it can be dangerous!
+
+Basically, if you use ``click`` on an element and want to use the *result* of the click, you can get into trouble if the result takes a long time.
+
+For example, something like ``#link_to_another_page click`` that causes a page load is probably a mistake -- the directive doesn't know how long to wait for the page to load, and will probably throw an error.
+
+Using ``click`` to interact with UI elements *on the same page* should be ok, as long as the result of interacting with the UI element happens really, really fast.
+
+The rule of thumb is, if a ``click`` loads a page or waits for an AJAX result, think twice about using it.
+

docs/developer_docs/environment.rst

@@ -27,6 +27,14 @@ KA Lite is like a normal django project, if you have done Django before, you wil
      
      pip install -r requirements_dev.txt
 
+#. Build static assets such as javascript::
+     
+     make assets
+
+#. Run the setup, which will bootstrap the database::
+     
+     kalite manage setup
+
 #. Run a development server and use development settings like this::
      
      kalite manage runserver --settings=kalite.project.settings.dev
@@ -39,36 +47,20 @@ Now, every time you work on your development environment, just remember to switc
 .. _github: https://github.com/learningequality/ka-lite
 
 
-Running directly from source
-____________________________
-
-
-KA Lite can also be run as a "source distribution" for development purposes.
-By this, we just mean a git checkout (from `our github <https://github.com/learningequality/ka-lite/>`_).
-
-.. note:: Running directly from source will also maintain all user data in that
-          same directory! This is convenient for having several versions of
-          kalite with different data on the same computer.
-
-If you are able to use pip and install conventional python packages from an
-online source, then the quickest option to install the latest stable release
-of KA Lite is ``pip install ka-lite` or `pip install ka-lite-static``.
-
-
 Static vs. Dynamic version
 __________________________
 
 Apart from Python itself, KA Lite depends on a couple of python applications,
-mainly from the Django ecology. These applications can be installed in two ways:
+mainly from the Django ecology. These dependencies can be installed in two ways:
 
-* **Dynamic**: That means that they are automatically installed through
-   *PIP* as a separate software package accessible to your whole system. This
-   is recommended if you run KA Lite and have internet access while installing
-   and updating.
+* **Dynamic**: Means dependencies are automatically installed through
+  *PIP* as a separate software package accessible to your whole system. This
+  is recommended if you run KA Lite and have internet access while installing
+  and updating.
 * **Static**: Static means that KA Lite is installed with all the external
-   applications bundled in. Use this method if you need to have KA Lite
-   installed from offline media or if KA Lite's dependencies are in conflict
-   with the system that you install upon.
+  dependencies bundled in. Use this method if you need to have KA Lite
+  installed from offline media or if KA Lite's dependencies are in conflict
+  with the system that you install upon.
 
 
 Virtualenv

docs/developer_docs/front_end_code.rst

@@ -1,5 +1,5 @@
-Front End Code
---------------
+Front-End Code
+==============
 
 All of our front end code is written in Javascript, with much of it using `Backbone.js <http://backbonejs.org>`__ (and its dependencies `jQuery <https://jquery.com/>`_ and `Underscore.js <http://underscorejs.org>`_).
 

docs/developer_docs/index.rst

@@ -5,13 +5,12 @@ Useful stuff our devs think that the rest of our devs ought to know about.
 
 .. toctree::
     Setting up your development environment <environment>
-    Developing Front End Code <front_end_code>
+    Front-End Code <front_end_code>
     Javascript Unit Tests <javascript_testing>
     Behavior-Driven Integration Tests <behave_testing>
-    Profiling KA Lite <profiling>
     Developer Utility Commands <utility>
     Logging <logging>
     Inline help <inline>
     Documentation <documentation>
-    Documentation screenshots <screenshots>
+    Accessibility <accessibility>
 

docs/index.rst

@@ -21,8 +21,7 @@ check our `Forums`_!
     Installation Guide <installguide/install_main>
     User Manual <usermanual/userman_main>
     FAQ <faq>
-    Contributing <developer_docs/contributing>
-    Dev Guide <developer_docs/index>
+    Developer Docs <developer_docs/index>
 
 
 .. include:: ../README.rst

docs/installguide/release_notes.rst

@@ -6,6 +6,32 @@ Release Notes
 
 This is a draft of what will be released. Notes are not fully accurate or final.
 
+Content
+^^^^^^^
+
+Contents have been rebuilt from upstream Khan Academy. We have solved issues
+regarding merging contents from Youtube and KhanAcademy.org, meaning that
+inaccuracies in 0.16 content packs are solved.
+
+ * Fixed/added in 0.17:
+    * Kannada, Malay, Polish, Swahili, Zulu
+ * Updated:
+    * Bulgarian, English, Bengali, Danish, German, Spanish (Castilian), French,
+      Hindi, Indonesian, Georgian, Portuguese (Brazil), Portuguese (Portugal),
+      Tamil, Xhosa
+ * Known issues:
+    * Arabic, we are still receiving wrong data from upstream APIs that we cannot fix.
+
+.. note::
+  After upgrading to version 0.17, you should visit the *Manage* tab to
+  upgrade your language and videos. You can also use
+  ``kalite manage retrievecontentpack`` to automate the download and
+  installation of new content packs.
+
+  You should **always** upgrade the English content pack because it contains
+  exercise data needed by the other content packs.
+
+
 New features
 ^^^^^^^^^^^^
 
@@ -50,16 +76,19 @@ Known issues
 
  * **Windows** needs at least Python 2.7.11. The Windows installer for KA Lite will install the latest version of Python. If you installed KA Lite in other way, and your Python installation is more than a year old, you probably have to upgrade Python - you can fetch the latest 2.7.12 version `here <https://www.python.org/downloads/windows/>`__.
  * **Windows** installer tray application option "Run on start" does not work, see `learningequality/installers#106 <https://github.com/learningequality/installers/issues/106>`__ (also contains `a work-around`<https://github.com/learningequality/installers/issues/106#issuecomment-237729680>__)
- * **Windows** 8 installation on 32bit is reported to take ~1 hour before eventually finishing.
- * **Development**: Selenium tests on Firefox 48+ needs the new `geckodriver <https://github.com/mozilla/geckodriver>`__ and the new Selenium 3 beta ``pip install selenium --pre --upgrade``
+ * **Windows 8** installation on 32bit is reported to take ~1 hour before eventually finishing.
+ * **Development**: Selenium tests on Firefox 48\+ needs the new `geckodriver <https://github.com/mozilla/geckodriver>`__ and the new Selenium 3 beta ``pip install selenium --pre --upgrade``.
+ * **Firefox 47**: Subtitles are mis-aligned in the video player. This is fixed by upgrading Firefox.
 
 
 .. note::
-    Code and command cleanups listed below are harmless if you installed KA Lite
-    using an installer and only relevant in these cases:
-     * You run a specialized setup or deployment
-     * Your deployment is 1½+ years old
-     * You're a KA Lite developer
+  Code and command cleanups listed below are harmless if you installed KA Lite
+  using an installer and only relevant in these cases:
+
+   * You run a specialized setup or deployment
+   * Your deployment is 1½+ years old
+   * You're a KA Lite developer
+
 
 Code cleanup
 ^^^^^^^^^^^^
@@ -81,6 +110,8 @@ Code cleanup
  * Static files are only served by Django's HTTP server in ``DEBUG=True`` mode. It was already handled by Cherrypy in other cases, and WSGI deployments are now required to implement this behavior.
  * We no longer release sdists (`tar.gz`) on PyPi, instead only `.whl`. :url-issue:`5299`
  * Unfinished backup commands removed. It's extremely easy to backup and restore (read: **duplicate**) a KA Lite setup, see :ref:`backup`.
+ * Removed profiling via ``PROFILE=yes`` (broken since 0.16)
+
 
 Debian/Ubuntu installer
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -310,15 +341,14 @@ Bug fixes
 General
 ^^^^^^^
 
-* KA Lite is officially supported on OSX 10.11 (El Capitan).
-* We've revamped the language packs into a new format, called content packs.
-  This results in significantly faster startup times across the board.
-.. WARNING::
-   You will have to redownload all your languages to fully support 0.16.
+ * KA Lite is officially supported on OSX 10.11 (El Capitan).
+ * We've revamped the language packs into a new format, called content packs.
+   This results in significantly faster startup times across the board.
+   .. WARNING::
+     You will have to redownload all your languages to fully support 0.16.
+ * We introduced a new beta inline help system. Check this out by going to the Facility management page and clicking "Show me how!"
+ * A lot of UI tweaks and bugfixes. KA Lite is now more stable than ever!
 
-* We introduced a new beta inline help system. Check this out by going to the
-  Facility management page and clicking "Show me how!"
-* A lot of UI tweaks and bugfixes. KA Lite is now more stable than ever!
 
 0.15.0
 ------
@@ -387,8 +417,8 @@ If you're updating a current Raspberry Pi installation, make sure to put this in
 
 
 
-Purging *pyc files
-^^^^^^^^^^^^^^^^^^
+Purging \*pyc files
+^^^^^^^^^^^^^^^^^^^
 
 Previously, kalite would look for ``*pyc`` files every time it was launched,
 and that was quite a waste since its only useful when upgrading. In dev