fixed issues with embedded API viewer (#886)

docs/Home.md

@@ -38,6 +38,8 @@ Browse the Jenkins issue tracker to see any [open issues](https://issues.jenkins
    viewer
  * Added a `SEED_JOB` script variable which provides access to the seed job,
    see [Job DSL Commands](Job-DSL-Commands#seed-job)
+ * Fixed issues with embedded API Viewer
+   ([#886](https://github.com/jenkinsci/job-dsl-plugin/pull/886))
  * Removed anything that has been deprecated in 1.42, see [Migration](Migration#migrating-to-142)
 * 1.48 (June 24 2016)
  * Added option to ignore missing DSL script files or empty wildcards

job-dsl-api-viewer/src/assets/javascripts/App.js

@@ -71,7 +71,7 @@ Marionette.Renderer.render = function(template, data) {
 
         loadSelectedDsl: function() {
             var url = $('.version-select').val();
-            return this.dslLoader.fetch(url).then(this.onDslFetchComplete.bind(this));
+            return this.dslLoader.fetch(url).then(this.onDslFetchComplete.bind(this), this.onDslFetchFailure.bind(this));
         },
 
         onDslFetchComplete: function(dsl) {
@@ -96,6 +96,10 @@ Marionette.Renderer.render = function(template, data) {
             this.allItems = allItems;
         },
 
+        onDslFetchFailure: function(dsl) {
+            $('.loading-inner').html('Error while loading data, see Jenkins logs for details.');
+        },
+
         initPluginList: function() {
             var pluginList = this.plugins;
             var pluginsView = new App.PluginsView({

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/EmbeddedApiDocGenerator.groovy

@@ -325,8 +325,14 @@ class EmbeddedApiDocGenerator {
 
     private static void generateHelp(JSONObject object, String text) {
         if (text) {
-            String normalizedText = text.replaceAll(/\r?\n/, '\n')
-            object.element('html', normalizedText).element('firstSentenceCommentText', firstSentence(normalizedText))
+            String normalizedText = text.replaceAll(/\r?\n/, '\n').trim()
+            if (normalizedText) {
+                object.element('html', normalizedText)
+                String firstSentence = firstSentence(normalizedText)
+                if (firstSentence) {
+                    object.element('firstSentenceCommentText', firstSentence)
+                }
+            }
         }
     }
 
@@ -339,6 +345,10 @@ class EmbeddedApiDocGenerator {
         // unescape HTML and remove leading/trailing spaces
         cleanText = unescapeHtml(cleanText).trim()
 
+        if (cleanText.empty) {
+            return ''
+        }
+
         BreakIterator iterator = BreakIterator.sentenceInstance
         iterator.text = new StringCharacterIterator(cleanText)
         cleanText[0..iterator.next() - 1].trim()

job-dsl-plugin/src/test/resources/expected-dsl.json

@@ -214,7 +214,7 @@
               ],
               "generated": true,
               "contextClass": "hudson.triggers.SCMTrigger",
-              "html": "<div>\n  Configure Jenkins to poll changes in SCM.\n\n  <p>\n  Note that this is going to be an expensive operation for CVS, as every polling\n  requires Jenkins to scan the entire workspace and verify it with the server.\n  Consider setting up a \"push\" trigger to avoid this overhead, as described in\n  <a href=\"https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project\">this document<\/a>\n<\/div>\n",
+              "html": "<div>\n  Configure Jenkins to poll changes in SCM.\n\n  <p>\n  Note that this is going to be an expensive operation for CVS, as every polling\n  requires Jenkins to scan the entire workspace and verify it with the server.\n  Consider setting up a \"push\" trigger to avoid this overhead, as described in\n  <a href=\"https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project\">this document<\/a>\n<\/div>",
               "firstSentenceCommentText": "Configure Jenkins to poll changes in SCM."
             }
           ]
@@ -232,7 +232,7 @@
               ],
               "generated": true,
               "contextClass": "hudson.triggers.TimerTrigger",
-              "html": "<div>\n  Provides a <a href=\"http://en.wikipedia.org/wiki/cron\">cron<\/a>-like feature\n  to periodically execute this project.\n\n  <p>\n  This feature is primarily for using Jenkins as a cron replacement,\n  and it is <b>not ideal for continuously building software projects<\/b>.\n\n  When people first start continuous integration, they are often so used to\n  the idea of regularly scheduled builds like nightly/weekly that they use\n  this feature. However, the point of continuous integration is to start\n  a build as soon as a change is made, to provide a quick feedback to the change.\n  To do that you need to\n  <a href=\"https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project\">hook up SCM change notification to Jenkins<\/a>.\n\n  <p>\n  So, before using this feature, stop and ask yourself if this is really what you want.\n\n<\/div>\n",
+              "html": "<div>\n  Provides a <a href=\"http://en.wikipedia.org/wiki/cron\">cron<\/a>-like feature\n  to periodically execute this project.\n\n  <p>\n  This feature is primarily for using Jenkins as a cron replacement,\n  and it is <b>not ideal for continuously building software projects<\/b>.\n\n  When people first start continuous integration, they are often so used to\n  the idea of regularly scheduled builds like nightly/weekly that they use\n  this feature. However, the point of continuous integration is to start\n  a build as soon as a change is made, to provide a quick feedback to the change.\n  To do that you need to\n  <a href=\"https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project\">hook up SCM change notification to Jenkins<\/a>.\n\n  <p>\n  So, before using this feature, stop and ask yourself if this is really what you want.\n\n<\/div>",
               "firstSentenceCommentText": "Provides a cron-like feature\n  to periodically execute this project."
             }
           ]
@@ -534,7 +534,7 @@
               "deprecated": false,
               "generated": true,
               "required": true,
-              "html": "<div>\n  This field follows the syntax of cron (with minor differences).\n  Specifically, each line consists of 5 fields separated by TAB or whitespace:\n  <pre>MINUTE HOUR DOM MONTH DOW<\/pre>\n  <table>\n    <tr>\n      <td>MINUTE<\/td>\n      <td>Minutes within the hour (0–59)<\/td>\n    <\/tr>\n    <tr>\n      <td>HOUR<\/td>\n      <td>The hour of the day (0–23)<\/td>\n    <\/tr>\n    <tr>\n      <td>DOM<\/td>\n      <td>The day of the month (1–31)<\/td>\n    <\/tr>\n    <tr>\n      <td>MONTH<\/td>\n      <td>The month (1–12)<\/td>\n    <\/tr>\n    <tr>\n      <td>DOW<\/td>\n      <td>The day of the week (0–7) where 0 and 7 are Sunday.<\/td>\n    <\/tr>\n  <\/table>\n  <p>\n    To specify multiple values for one field, the following operators are\n    available. In the order of precedence,\n  <\/p>\n  <ul>\n    <li><code>*<\/code> specifies all valid values<\/li>\n    <li><code>M-N<\/code> specifies a range of values<\/li>\n    <li><code>M-N/X<\/code> or <code>*/X<\/code> steps by intervals of X through the specified range or whole valid range<\/li>\n    <li><code>A,B,...,Z<\/code> enumerates multiple values<\/li>\n  <\/ul>\n  <p>\n    To allow periodically scheduled tasks to produce even load on the system,\n    the symbol <code>H<\/code> (for “hash”) should be used wherever possible.\n    For example, using <code>0 0 * * *<\/code> for a dozen daily jobs\n    will cause a large spike at midnight.\n    In contrast, using <code>H H * * *<\/code> would still execute each job once a day,\n    but not all at the same time, better using limited resources.\n  <\/p><p>\n    The <code>H<\/code> symbol can be used with a range. For example, <code>H H(0-7) * * *<\/code>\n    means some time between 12:00 AM (midnight) to 7:59 AM.\n    You can also use step intervals with <code>H<\/code>, with or without ranges.\n  <\/p><p>\n    The <code>H<\/code> symbol can be thought of as a random value over a range,\n    but it actually is a hash of the job name, not a random function, so that\n    the value remains stable for any given project.\n  <\/p>\n  <p>\n      Beware that for the day of month field, short cycles such as <code>*/3<\/code> or <code>H/3<\/code> will not work consistently near the end of most months, due to variable month lengths.\n      For example, <code>*/3<\/code> will run on the 1st, 4th, …31st days of a long month, then again the next day of the next month.\n      Hashes are always chosen in the 1-28 range, so <code>H/3<\/code> will produce a gap between runs of between 3 and 6 days at the end of a month.\n      (Longer cycles will also have inconsistent lengths but the effect may be relatively less noticeable.)\n  <\/p>\n  <p>\n    Empty lines and lines that start with <code>#<\/code> will be ignored as comments.\n  <\/p><p>\n    In addition, <code>@yearly<\/code>, <code>@annually<\/code>, <code>@monthly<\/code>,\n    <code>@weekly<\/code>, <code>@daily<\/code>, <code>@midnight<\/code>,\n    and <code>@hourly<\/code> are supported as convenient aliases.\n    These use the hash system for automatic balancing.\n    For example, <code>@hourly<\/code> is the same as <code>H * * * *<\/code> and could mean at any time during the hour.\n    <code>@midnight<\/code> actually means some time between 12:00 AM and 2:59 AM.\n  <\/p><p>\n    Examples:\n  <\/p>\n<pre>\n# every fifteen minutes (perhaps at :07, :22, :37, :52)\nH/15 * * * *\n# every ten minutes in the first half of every hour (three times, perhaps at :04, :14, :24)\nH(0-29)/10 * * * *\n# once every two hours every weekday (perhaps at 10:38 AM, 12:38 PM, 2:38 PM, 4:38 PM)\nH 9-16/2 * * 1-5\n# once a day on the 1st and 15th of every month except December\nH H 1,15 1-11 *\n<\/pre>\n<\/div>\n",
+              "html": "<div>\n  This field follows the syntax of cron (with minor differences).\n  Specifically, each line consists of 5 fields separated by TAB or whitespace:\n  <pre>MINUTE HOUR DOM MONTH DOW<\/pre>\n  <table>\n    <tr>\n      <td>MINUTE<\/td>\n      <td>Minutes within the hour (0–59)<\/td>\n    <\/tr>\n    <tr>\n      <td>HOUR<\/td>\n      <td>The hour of the day (0–23)<\/td>\n    <\/tr>\n    <tr>\n      <td>DOM<\/td>\n      <td>The day of the month (1–31)<\/td>\n    <\/tr>\n    <tr>\n      <td>MONTH<\/td>\n      <td>The month (1–12)<\/td>\n    <\/tr>\n    <tr>\n      <td>DOW<\/td>\n      <td>The day of the week (0–7) where 0 and 7 are Sunday.<\/td>\n    <\/tr>\n  <\/table>\n  <p>\n    To specify multiple values for one field, the following operators are\n    available. In the order of precedence,\n  <\/p>\n  <ul>\n    <li><code>*<\/code> specifies all valid values<\/li>\n    <li><code>M-N<\/code> specifies a range of values<\/li>\n    <li><code>M-N/X<\/code> or <code>*/X<\/code> steps by intervals of X through the specified range or whole valid range<\/li>\n    <li><code>A,B,...,Z<\/code> enumerates multiple values<\/li>\n  <\/ul>\n  <p>\n    To allow periodically scheduled tasks to produce even load on the system,\n    the symbol <code>H<\/code> (for “hash”) should be used wherever possible.\n    For example, using <code>0 0 * * *<\/code> for a dozen daily jobs\n    will cause a large spike at midnight.\n    In contrast, using <code>H H * * *<\/code> would still execute each job once a day,\n    but not all at the same time, better using limited resources.\n  <\/p><p>\n    The <code>H<\/code> symbol can be used with a range. For example, <code>H H(0-7) * * *<\/code>\n    means some time between 12:00 AM (midnight) to 7:59 AM.\n    You can also use step intervals with <code>H<\/code>, with or without ranges.\n  <\/p><p>\n    The <code>H<\/code> symbol can be thought of as a random value over a range,\n    but it actually is a hash of the job name, not a random function, so that\n    the value remains stable for any given project.\n  <\/p>\n  <p>\n      Beware that for the day of month field, short cycles such as <code>*/3<\/code> or <code>H/3<\/code> will not work consistently near the end of most months, due to variable month lengths.\n      For example, <code>*/3<\/code> will run on the 1st, 4th, …31st days of a long month, then again the next day of the next month.\n      Hashes are always chosen in the 1-28 range, so <code>H/3<\/code> will produce a gap between runs of between 3 and 6 days at the end of a month.\n      (Longer cycles will also have inconsistent lengths but the effect may be relatively less noticeable.)\n  <\/p>\n  <p>\n    Empty lines and lines that start with <code>#<\/code> will be ignored as comments.\n  <\/p><p>\n    In addition, <code>@yearly<\/code>, <code>@annually<\/code>, <code>@monthly<\/code>,\n    <code>@weekly<\/code>, <code>@daily<\/code>, <code>@midnight<\/code>,\n    and <code>@hourly<\/code> are supported as convenient aliases.\n    These use the hash system for automatic balancing.\n    For example, <code>@hourly<\/code> is the same as <code>H * * * *<\/code> and could mean at any time during the hour.\n    <code>@midnight<\/code> actually means some time between 12:00 AM and 2:59 AM.\n  <\/p><p>\n    Examples:\n  <\/p>\n<pre>\n# every fifteen minutes (perhaps at :07, :22, :37, :52)\nH/15 * * * *\n# every ten minutes in the first half of every hour (three times, perhaps at :04, :14, :24)\nH(0-29)/10 * * * *\n# once every two hours every weekday (perhaps at 10:38 AM, 12:38 PM, 2:38 PM, 4:38 PM)\nH 9-16/2 * * 1-5\n# once a day on the 1st and 15th of every month except December\nH H 1,15 1-11 *\n<\/pre>\n<\/div>",
               "firstSentenceCommentText": "This field follows the syntax of cron (with minor differences)."
             }
           ]