#207: added help template file for html-app. updated text for help page

src/scancode/format.py

@@ -27,6 +27,7 @@
 from collections import OrderedDict
 from operator import itemgetter
 from os.path import abspath
+from os.path import basename
 from os.path import dirname
 from os.path import exists
 from os.path import expanduser
@@ -68,6 +69,16 @@ def as_html_app(scanned_path, output_file):
     return template.render(assets_dir=assets_dir, scanned_path=scanned_path)
 
 
+def get_html_app_help(output_filename):
+    """
+    Return an HTML string containing html-app help page with a reference back
+    to the main app
+    """
+    template = get_template(get_template_dir('html-app'), template_name='help_template.html')
+
+    return template.render(main_app=output_filename)
+
+
 class HtmlAppAssetCopyWarning(Exception):
     pass
 
@@ -109,17 +120,24 @@ def create_html_app_assets(results, output_file):
             raise HtmlAppAssetCopyWarning()
         assets_dir = join(get_template_dir('html-app'), 'assets')
 
+        # delete old assets
         tgt_dirs = get_html_app_files_dirs(output_file)
         target_dir = join(*tgt_dirs)
         if exists(target_dir):
             fileutils.delete(target_dir)
+
+        # copy assets
         fileutils.copytree(assets_dir, target_dir)
 
         # write json data
         import json
         root_path, assets_dir = get_html_app_files_dirs(output_file)
         with open(join(root_path, assets_dir, 'data.json'), 'w') as f:
             f.write('data=' + json.dumps(results))
+
+        # create help file
+        with open(join(root_path, assets_dir, 'help.html'), 'w') as f:
+            f.write(get_html_app_help(basename(output_file.name)))
     except HtmlAppAssetCopyWarning, w:
         raise w
     except Exception, e:

src/scancode/templates/html-app/assets/index.html → src/scancode/templates/html-app/help_template.html

@@ -56,6 +56,9 @@
                 <li>
                     <a href="#terms">Terms</a>
                 </li>
+                <li>
+                    <a href="#howto">How To</a>
+                </li>
             </ul>
         </div>
         <!-- /#sidebar-wrapper -->
@@ -65,33 +68,36 @@
             <div class="container-fluid">
                 <div class="row">
                     <div class="col-lg-12">
-                        <a href="#" class="btn btn-default" id="menu-toggle"><span class="glyphicon glyphicon-triangle-left" aria-hidden="true"></span> Back to scan results</a>
+                        <a href="../{{main_app}}" class="btn btn-default" id="menu-toggle"><span class="glyphicon glyphicon-triangle-left" aria-hidden="true"></span> Back to scan results</a>
                         <h1>ScanCode Toolkit</h1>
                         <h3 id="#summary">Scan Summaries</h3>
                         <h4>License Summary</h4>
-                        <p>The License Summary displays a bar chart of the number of times a detected license appears.</p>
+                        <p>The License Summary displays a bar chart of the number of times a detected license appears. The "Total Files Scanned" displays the number of files that were scanned. As you select a directory in the file tree, the number will update to show the number of files scanned in that directory. In the chart summary we have included "No License Found" to represent the number of files that did not have a license detected.</p>
                         <h4>Copyright Summary</h4>
-                        <p>The Copyright Summary displays a bar chart of the number of times a detected copyright holder appears. In the file tree view, the chart results can be filtered to show a selected directory or file.</p>
+                        <p>The Copyright Summary displays a bar chart of the number of times a detected copyright holder appears. The "Total Files Scanned" displays the number of files that were scanned. As you select a directory in the file tree, the number will update to show the number of files scanned in that directory. In the chart summary we have included "No Copyright Found" to represent the number of files that did not have a copyright holder detected.</p>
                         <h3 id="#clues">Clues</h3>
-                        <p>The license, copyright, email, and url clues from a scan.</p>
+                        <p>In the Clues tab, the available clues detected by ScanCode are shown in a tabular format. Currently, the license, copyright, email, and url clues are available from a scan.</p>
+                        <b>Column header descriptions:</b>
+                        <ul>
+                            <li>Path - Location of component</li>
+                            <li>What - Type of scan clue (license, copyright, url, email)</li>
+                            <li>Start Line - Starting line number of the clue</li>
+                            <li>End Line - Ending line number of the clue</li>
+                            <li>Info - Detected clue information</li>
+                        </ul>
                         <h3 id="file-details">File Details</h3>
                         <p>The file information for a component (For example, file type, sha1, file size)</p>
                         <h3 id="package-details">Package Details</h3>
+                        <p>Package information that is typically derived from a package manifest such as a RPM metadata, an NPM, a gem, a wheel, a Jar, etc.</p>
                         <h3 id="data-processing">Data Processing</h3>
                         <h4>Filtering</h4>
                         <p>In the file tree view, the scan results that are shown in the table or in the summary charts can be filtered by selecting a directory or file.</p>
                         <h4>Sorting</h4>
                         <p>Column sorting can be used by selecting the ascending or descending arrow of the column you would like to sort.</p>
                         <h4>Searching</h4>
                         <p>The results in the table view can be searched using the Search box</p>
-                        <h3 id="terms">Terms</h3>
-                        <ul>
-                            <li>Path - Location of component</li>
-                            <li>What - Type of scan clue (license, copyright, url, email)</li>
-                            <li>Start Line - Starting line number of the clue</li>
-                            <li>End Line - Ending line number of the clue</li>
-                            <li>Info - Detected clue information</li>
-                        </ul>
+                        <h3 id="howto">How To</h3>
+                        <p>Visit the <a href="https://github.com/nexB/scancode-toolkit/wiki/How-To:-Run-a-scan">ScanCode Wiki </a> for a series of How To wiki entries that provide step by step instructions to getting started with ScanCode.</p>
                     </div>
                 </div>
             </div>

src/scancode/templates/html-app/template.html

@@ -45,7 +45,7 @@
             <span class="navbar-brand icon-primary"><a href="https://github.com/nexB/scancode-toolkit/">ScanCode</a> scan results for: {{ scanned_path }}</span>
         </div>
           <ul class="nav navbar-nav navbar-right">
-            <li><a href="{{ assets_dir }}/index.html">Help</a></li>
+            <li><a href="{{ assets_dir }}/help.html">Help</a></li>
             <li><a href="http://www.nexb.com">Made by nexB</a></li>
          </ul>
       </div>