Update docs for auto js file discovery

This patch updates the docs following the merge of most of the auto js
file discovery patches.

It also fixes a few minor issues with the documentation.

Change-Id: I419b7c861683ccb67f0cbadac666627602e3006c
Partially-Implements: blueprint angular-docs

doc/source/topics/angularjs.rst

@@ -64,19 +64,26 @@ is likely to be used across many parts of horizon.
 When adding code to horizon, consider whether it is panel-specific or should be
 broken out as a reusable utility or widget.
 
-Panel-specific code is in ``openstack_dashboard/static/dashboard/``.
-
 The modal directive is a good example of the file structure. This is a reusable
 component:
 ::
 
   horizon/static/framework/widgets/modal/
   ├── modal.controller.js
-  ├── modal.service.js
   ├── modal.module.js
+  ├── modal.service.js
   ├── modal.spec.js
   └── simple-modal.html
 
+Panel-specific code is in ``openstack_dashboard/static/dashboard/``. For example:
+::
+
+  openstack_dashboard/static/dashboard/workflow/
+  ├── decorator.service.js
+  ├── workflow.module.js
+  ├── workflow.module.spec.js
+  └── workflow.service.js
+
 For larger components, such as workflows with multiple steps, consider breaking
 the code down further. The Angular **Launch Instance** workflow,
 for example, has one directory per step
@@ -85,10 +92,12 @@ for example, has one directory per step
 Testing
 =======
 
-1. Open <dev_server_ip>/jasmine in a browser. The development server can be run
+1. Open <dev_server_ip:port>/jasmine in a browser. The development server can be run
    with``./run_tests.sh --runserver`` from the horizon root directory.
 2. ``npm run test`` from the horizon root directory.
 
+The code linting job can be run with ``npm run lint``.
+
 For more detailed information, see :doc:`javascript_testing`.
 
 Translation (Internationalization and Localization)
@@ -124,9 +133,8 @@ Creating your own panel
   as an example.
 
 .. Note::
-  File inclusion is likely to be automated soon, after this
+  Currently, Angular module names must still be manually declared with
-  `blueprint <https://blueprints.launchpad.net/horizon/+spec/auto-js-file-finding>`_
+  ``ADD_ANGULAR_MODULES``, even when using automatic file discovery.
-  is completed.
 
 This section serves as a basic introduction to writing your own panel for
 horizon, using AngularJS. A panel may be included with the plugin system, or it may be
@@ -135,36 +143,23 @@ part of the upstream horizon project.
 Upstream
 --------
 
-If you are adding a panel to horizon, add the relevant ``.js`` and ``.spec.js``
+JavaScript files can be discovered automatically, handled manually, or a mix of
-files to one of the dashboards in ``openstack_dashboard/enabled/``.
+the two. Where possible, use the automated mechanism.
-An example can be found at ``openstack_dashboard/enabled/_10_project.py``:
+To use the automatic functionality, add::
-::
+  AUTO_DISCOVER_STATIC_FILES = True
+to your ``enabled/___.py``. To make this possible, you need to follow some
+structural conventions:
 
-  LAUNCH_INST = 'dashboard/launch-instance/'
+  - Static files should be put in a ``static/`` folder, which should be found directly under
+    the folder for the dashboard/panel/panel groups Python package.
+  - JS code that defines an Angular module should be in a file with extension of ``.module.js``.
+  - JS code for testing should be named with extension of ``.mock.js`` and of ``.spec.js``.
+  - Angular templates should have extension of ``.html``.
 
-  ADD_JS_FILES = [
+You can read more about the functionality in the
-    ...
+:ref:`auto_discover_static_files` section of the settings documentation.
-    LAUNCH_INST + 'launch-instance.js',
-    LAUNCH_INST + 'launch-instance.model.js',
-    LAUNCH_INST + 'source/source.js',
-    LAUNCH_INST + 'flavor/flavor.js',
-    ...
-  ]
 
-  ADD_JS_SPEC_FILES = [
+To manually add files, add the following arrays and file paths to the enabled file:
-    ...
-    LAUNCH_INST + 'launch-instance.spec.js',
-    LAUNCH_INST + 'launch-instance.model.spec.js',
-    LAUNCH_INST + 'source/source.spec.js',
-    LAUNCH_INST + 'flavor/flavor.spec.js',
-    ...
-  ]
-
-Plugins
--------
-
-Add a new panel/ panel group/ dashboard (See :doc:`tutorial`). Add your files
-to the relevant arrays in your new enabled files:
 ::
 
   ADD_JS_FILES = [
@@ -178,3 +173,33 @@ to the relevant arrays in your new enabled files:
     'path_to/my_angular_code.spec.js',
     ...
   ]
+
+  ADD_ANGULAR_MODULES = [
+    ...
+    'angular.module',
+    ...
+  ]
+
+Plugins
+-------
+
+Add a new panel/ panel group/ dashboard (See :doc:`tutorial`). JavaScript file
+inclusion is the same as the Upstream process.
+
+To include external stylesheets, you must ensure that ``ADD_SCSS_FILES`` is
+defined in your enabled file, and add the relevant filepath, as below:
+::
+
+  ADD_SCSS_FILES = [
+    ...
+    'path_to/my_styles.scss',
+    ...
+  ]
+
+.. warning::
+  We highly recommend using a single SCSS file for your plugin. SCSS supports
+  nesting with @import, so if you have multiple files (i.e. per panel styling)
+  it is best to import them all into one, and include that single file. You can
+  read more in the `SASS documentation`_.
+
+.. _SASS documentation: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#import

doc/source/topics/javascript_testing.rst

@@ -30,7 +30,7 @@ Running Tests
 
 Tests can be run in two ways:
 
-  1. Open <dev_server_ip>/jasmine in a browser. The development server can be
+  1. Open <dev_server_ip:port>/jasmine in a browser. The development server can be
      run with ``./run_tests.sh --runserver`` from the horizon root directory.
   2. ``npm run test`` from the horizon root directory. This runs Karma,
      so it will run all the tests against PhantomJS and generate coverage
@@ -53,11 +53,6 @@ found at ``horizon/.coverage-karma/`` (framework tests) and
 Writing Tests
 =============
 
-.. Note::
-  File inclusion is likely to be automated soon, after this
-  `blueprint <https://blueprints.launchpad.net/horizon/+spec/auto-js-file-finding>`_
-  is completed.
-
 Jasmine uses suites and specs:
   * Suites begin with a call to ``describe``, which takes two parameters; a
     string and a function. The string is a name or title for the spec suite,
@@ -68,25 +63,24 @@ Jasmine uses suites and specs:
     the code. An expectation in Jasmine is an assertion that is either true or
     false; every expectation in a spec must be true for the spec to pass.
 
-Horizon Tests
+``.spec.js`` files can be handled manually or automatically. To use the
--------------
+automatic file discovery add::
+  AUTO_DISCOVER_STATIC_FILES = True
+to your enabled file. JS code for testing should use the extensions
+``.mock.js`` and ``.spec.js``.
 
-Horizon tests are included in
+You can read more about the functionality in the
-``horizon/test/jasmine/jasmine_tests.py``.
+:ref:`auto_discover_static_files` section of the settings documentation.
 
-Add your test to the ``specs`` array, code sources to the ``dashboard_sources``
+To manually add specs, add the following array and relevant file paths to your
-array, and any templates to the ``externalTemplates`` array. Horizon tests
+enabled file:
-cover reusable components, as well as api functionality, whilst dashboard
+::
-tests cover specific panels and their logic. The tests themselves are kept in
-the same directory as the implementation they are testing.
 
-OpenStack Dashboard Tests
+  ADD_JS_SPEC_FILES = [
--------------------------
+    ...
-
+    'path_to/my_angular_code.spec.js',
-Dashboard tests are included in the relevant dashboard enabled file, such as
+    ...
-``openstack_dashboard/enabled/_10_project.py``.
+  ]
-
-Add your tests to the ``ADD_JS_SPEC_FILES`` array.
 
 Examples
 ========
@@ -104,8 +98,8 @@ File tree:
 
   horizon/static/framework/widgets/modal
   ├── modal.controller.js
-  ├── modal.service.js
   ├── modal.module.js
+  ├── modal.service.js
   └── modal.spec.js
 
 Lines added to ``horizon/test/jasmine/jasmine_tests.py``:

doc/source/topics/settings.rst

@@ -1247,6 +1247,8 @@ A list of scss files to be included in the compressed set of files that are
 loaded on every page. We recommend one scss file per dashboard, use @import if
 you need to include additional scss files for panels.
 
+.. _auto_discover_static_files:
+
 ``AUTO_DISCOVER_STATIC_FILES``
 ------------------------------