Merge pull request #7 from linz/doc-update

More documentation and associated images
linz · Jul 26, 2017 · 9da2b6e · 9da2b6e
2 parents 475a0ac + e196cfb
commit 9da2b6e
Show file tree

Hide file tree

Showing 17 changed files with 146 additions and 13 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -4,6 +4,14 @@ Change Log
 
 All notable changes to this project will be documented in this file.
 
+0.4.1 - 2017-07-27
+==================
+
+Changed
+-------
+
+ * More thorough documentation added
+
 0.4.0 - 2017-07-24
 ==================
 

diff --git a/README.rst b/README.rst
@@ -8,6 +8,9 @@ QGIS Script Assistant Plugin
 .. image:: https://travis-ci.org/linz/qgis-scriptassistant-plugin.svg?branch=master
     :target: https://travis-ci.org/linz/qgis-scriptassistant-plugin
 
+.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat&maxAge=86400
+    :target: http://qgis-script-assistant-plugin.readthedocs.io/en/latest/?badge=latest
+
 This is a QGIS plugin with three helper tools for QGIS development purposes:
 
 * Reload processing user scripts into QGIS from any existing directory
@@ -35,7 +38,7 @@ See the full docs on `readthedocs <http://qgis-script-assistant-plugin.readthedo
 Tests
 =====
 
-On installation, the plugin is configured to test itself. Click the Run Tests button to test.
+On installation, the plugin is configured to test itself. Click the Test Scripts button to test.
 
 Limitations
 ===========

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -2,4 +2,71 @@
 Configuration
 =============
 
-The plugin is configured using the Settings Dialog.
+The Script Assistant plugin is configured using the settings dialog. The plugin is designed to hold multiple project configurations, so that it's easy to switch between development tasks.
+
+The Settings Dialog
+===================
+
+.. image:: images/settings.png
+    :align: center
+
+Default settings
+----------------
+
+The plugin comes with one configuration pre-installed - this configuration allows the plugin to test itself.
+
+.. image:: images/settings_dialog.png
+    :align: center
+
+On install, you can immediately select the Test Scripts button.
+
+.. image:: images/test_scripts.png
+    :align: center
+
+User settings
+-------------
+
+To add a new Script Assistant configuration, change the name in the configuration combo box and then type in or select the appropriate settings in the dialog. Click Save to store the configuration.
+
+Don't reload tests setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: images/dont_reload.png
+    :align: center
+
+This setting turns off the use of ``reload()`` to reload test modules. It'll run tests faster but the test won't update if it has been edited in an external text editor.
+
+Playback UI tests in slow motion setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: images/playback_ui_tests.png
+    :align: center
+
+This setting requires some additional code within the tests to actually do anything.
+
+This setting simply calls ``test_x.run_tests(view_tests=True)`` instead of ``test_x.run_tests()``. The ``view_tests`` parameter is used to include a function in testing that repaints Qt widgets and sleeps for a designated time period. This allows UI tests to be visualised.
+
+Directory validation
+--------------------
+
+Directories displayed in red text cannot be found in the file system so are invalid. The Save action is unavailable if there are invalid directories.
+
+.. image:: images/invalid_dir.png
+    :align: center
+
+Save confirmation
+-----------------
+
+If settings have been modified but not yet saved, an asterisk is displayed in the dialog title.
+
+.. image:: images/unsaved_asterisk.png
+    :align: center
+
+If a dialog is closed in any way with unsaved settings, the user will be asked to confirm via the Save Confirmation dialog. If the user opts not to save, the settings entered into the settings dialog will still be used for the current QGIS session - but they won't be available in subsequent QGIS sessions.
+
+The Settings Configuration File
+===============================
+
+Settings are saved to a configuration file stored in the ``.qgis2/scriptassistant`` directory in the user folder (the exact location differs depending on operating system). If a group of users require similar configurations, the settings file can be shared between users. User directories will need to be amended.
+
+The settings file should generally be modified by changing settings in the settings dialog, not by directly editing it. It is provided in .ini format for convenience.
diff --git a/docs/images/add_test_data.png b/docs/images/add_test_data.png
diff --git a/docs/images/dont_reload.png b/docs/images/dont_reload.png
diff --git a/docs/images/invalid_dir.png b/docs/images/invalid_dir.png
diff --git a/docs/images/playback_ui_tests.png b/docs/images/playback_ui_tests.png
diff --git a/docs/images/plugin_test.gif b/docs/images/plugin_test.gif
diff --git a/docs/images/reload_scripts.png b/docs/images/reload_scripts.png
diff --git a/docs/images/settings.png b/docs/images/settings.png
diff --git a/docs/images/settings_dialog.png b/docs/images/settings_dialog.png
diff --git a/docs/images/run_tests.gif → docs/images/test_scripts.gif b/docs/images/run_tests.gif → docs/images/test_scripts.gif
diff --git a/docs/images/test_scripts.png b/docs/images/test_scripts.png
diff --git a/docs/images/unsaved_asterisk.png b/docs/images/unsaved_asterisk.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,15 @@
 
-Script Assistant Docs
-=====================
+QGIS Script Assistant Plugin Docs
+=================================
+
+This is a QGIS plugin with three helper tools for QGIS development purposes.
+
+Here it is in action - testing itself:
+
+.. image:: images/plugin_test.gif
+    :align: center
+
+To learn more, check out the feature overview and configuration guide below.
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -7,23 +7,69 @@ This is a QGIS plugin with three helper tools for QGIS development purposes.
 Reload Scripts
 ==============
 
+.. image:: images/reload_scripts.png
+    :align: center
+
 Load / reload processing user scripts into QGIS from any existing directory.
 
 .. image:: images/reload_scripts.gif
     :align: center
 
-Run Tests
-=========
+The Reload Scripts tool simply copies processing scripts from the configured directory to the QGIS processing scripts directory, and then reloads the processing toolbox in QGIS. If a script already exists with the same name, it will be overwritten without warning.
+
+Test Scripts
+============
+
+.. image:: images/test_scripts.png
+    :align: center
 
 Run tests within QGIS in a way that makes them configurable for local and Travis-CI testing without any manual amendments.
 
-.. image:: images/run_tests.gif
+.. image:: images/test_scripts.gif
     :align: center
 
+The test list
+-------------
+
+The test list is constructed by finding any file in the configured test directory with a file name starting with ``test_`` and ending with ``.py``. It does not (currently) check folders within the test directory.
+
+Every time you select the dropdown to the right of the Test Scripts button, the test list reloads from the tests directory. So if you're switching branches in git, you'll always be running the tests from the same branch you've checked out.
+
+Running a test
+--------------
+
+Select a test from the test list to run it.
+
+The QGIS Python Console will be opened (if it isn't already visible) to print test results.
+
+``reload()`` is used to reload the test module. This allows the tests to be edited using an external text editor and then recompiled in QGIS. This functionality can be switched off in settings if it isn't required.
+
+Running a test will also apply that test as the default action for the Test Scripts button - to repetitively run the same test, there is no need to select it from the test list again and again, just click on Test Scripts after the first run.
+
+Running all tests
+-----------------
+
+There is always an additional option in the test list to run all tests. This option collects tests in the same way that the test list is constructed and runs the lot.
+
+Testing using Travis-CI
+-----------------------
+
+The plugin `repository <https://github.com/linz/qgis-scriptassistant-plugin>`_ contains an example of how to run these same tests using Travis-CI.
+
+Thanks to Boundless for making this possible using `qgis-testing-environment-docker <https://github.com/boundlessgeo/qgis-testing-environment-docker>`_!
+
 Add Test Data
 =============
 
-Add all of the test data referred to in those tests with a click.
+.. image:: images/add_test_data.png
+    :align: center
+
+Add all of the test data referred to in a test with a click.
 
 .. image:: images/add_test_data.gif
     :align: center
+
+Adding shapefiles used in tests
+-------------------------------
+
+The Add Test Data tool checks the last test script that was run for references to ``.shp`` files. Any shapefile matches from the configured testdata directory are then added to the QGIS layer registry.
diff --git a/scriptassistant/metadata.txt b/scriptassistant/metadata.txt
@@ -1,23 +1,23 @@
 [general]
 name=Script Assistant
-description=This plugin helps to reload and test Processing scripts
-about=This plugin moves and overwrites scripts in the default QGIS script location from another directory. Useful for example if you are modifying scripts in a .git repository and want to deploy them.
+description=This plugin helps to reload users scripts and test scripts and plugins
+about=This plugin moves and overwrites scripts in the default QGIS script location from another directory. Useful for example if you are modifying scripts in a .git repository and want to reload them to QGIS.
 version=dev
 
 qgisMinimumVersion=2.14
 
 author=Land Information New Zealand
 email=dsilk@linz.govt.nz
 
-homepage=https://github.com/linz/qgis-scriptassistant-plugin
+homepage=http://qgis-script-assistant-plugin.readthedocs.io/en/latest/index.html
 repository=https://github.com/linz/qgis-scriptassistant-plugin
 tracker=https://github.com/linz/qgis-scriptassistant-plugin/issues
 changelog=https://github.com/linz/qgis-scriptassistant-plugin/blob/master/CHANGELOG.rst
 
 tags=processing, development, testing
 
 category=Plugins
-icon=icon.png
+icon=images/test_scripts.png
 
-experimental=True
+experimental=False
 deprecated=False