Add half-year directive (%h) for formatting dates and improve descriptions to include extra date formatting options

src/lib/dates.js

@@ -370,11 +370,19 @@ exports.cleanDate = function(v, dflt, calendar) {
  */
 
 /*
- * modDateFormat: Support world calendars, and add one item to
+ * modDateFormat: Support world calendars, and add two items to
  * d3's vocabulary:
  * %{n}f where n is the max number of digits of fractional seconds
+ * %h formats: half of the year as a decimal number [1,2]
  */
 var fracMatch = /%\d?f/g;
+var halfYearMatch = /%h/g;
+var quarterToHalfYear = {
+    '1': '1',
+    '2': '1',
+    '3': '2',
+    '4': '2',
+};
 function modDateFormat(fmt, x, formatter, calendar) {
     fmt = fmt.replace(fracMatch, function(match) {
         var digits = Math.min(+(match.charAt(1)) || 6, 6);
@@ -386,6 +394,10 @@ function modDateFormat(fmt, x, formatter, calendar) {
 
     var d = new Date(Math.floor(x + 0.05));
 
+    fmt = fmt.replace(halfYearMatch, function() {
+        return quarterToHalfYear[formatter('%q')(d)];
+    });
+
     if(isWorldCalendar(calendar)) {
         try {
             fmt = Registry.getComponentMethod('calendars', 'worldCalFmt')(fmt, x, calendar);

src/plots/cartesian/axis_format_attributes.js

@@ -0,0 +1,47 @@
+'use strict';
+
+var docs = require('../../constants/docs');
+var FORMAT_LINK = docs.FORMAT_LINK;
+var DATE_FORMAT_LINK = docs.DATE_FORMAT_LINK;
+
+function axisHoverFormat(x, noDates) {
+    return {
+        valType: 'string',
+        dflt: '',
+        editType: 'none',
+        description: (
+            noDates ? descriptionOnlyNumbers : descriptionWithDates
+        )('hover text', x) + [
+            'By default the values are formatted using ' + (
+                noDates ?
+                    'generic number format' :
+                    ('`' + x + 'axis.hoverformat`')
+            ) + '.',
+        ].join(' ')
+    };
+}
+
+function descriptionOnlyNumbers(label, x) {
+    return [
+        'Sets the ' + label + ' formatting rule' + (x ? 'for `' + x + '` ' : ''),
+        'using d3 formatting mini-languages',
+        'which are very similar to those in Python. For numbers, see: ' + FORMAT_LINK + '.'
+    ].join(' ');
+}
+
+function descriptionWithDates(label, x) {
+    return descriptionOnlyNumbers(label, x) + [
+        ' And for dates see: ' + DATE_FORMAT_LINK + '.',
+        'We add two items to d3\'s date formatter:',
+        '*%h* for half of the year as a decimal number as well as',
+        '*%{n}f* for fractional seconds',
+        'with n digits. For example, *2016-10-13 09:15:23.456* with tickformat',
+        '*%H~%M~%S.%2f* would display *09~15~23.46*'
+    ].join(' ');
+}
+
+module.exports = {
+    axisHoverFormat: axisHoverFormat,
+    descriptionOnlyNumbers: descriptionOnlyNumbers,
+    descriptionWithDates: descriptionWithDates
+};

src/plots/cartesian/layout_attributes.js

@@ -5,10 +5,7 @@ var colorAttrs = require('../../components/color/attributes');
 var dash = require('../../components/drawing/attributes').dash;
 var extendFlat = require('../../lib/extend').extendFlat;
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
-
-var docs = require('../../constants/docs');
-var FORMAT_LINK = docs.FORMAT_LINK;
-var DATE_FORMAT_LINK = docs.DATE_FORMAT_LINK;
+var descriptionWithDates = require('../../plots/cartesian/axis_format_attributes').descriptionWithDates;
 
 var ONEDAY = require('../../constants/numerical').ONEDAY;
 var constants = require('./constants');
@@ -702,16 +699,7 @@ module.exports = {
         valType: 'string',
         dflt: '',
         editType: 'ticks',
-        description: [
-            'Sets the tick label formatting rule using d3 formatting mini-languages',
-            'which are very similar to those in Python. For numbers, see:',
-            FORMAT_LINK,
-            'And for dates see:',
-            DATE_FORMAT_LINK,
-            'We add one item to d3\'s date formatter: *%{n}f* for fractional seconds',
-            'with n digits. For example, *2016-10-13 09:15:23.456* with tickformat',
-            '*%H~%M~%S.%2f* would display *09~15~23.46*'
-        ].join(' ')
+        description: descriptionWithDates('tick label')
     },
     tickformatstops: templatedArray('tickformatstop', {
         enabled: {
@@ -750,16 +738,7 @@ module.exports = {
         valType: 'string',
         dflt: '',
         editType: 'none',
-        description: [
-            'Sets the hover text formatting rule using d3 formatting mini-languages',
-            'which are very similar to those in Python. For numbers, see:',
-            FORMAT_LINK,
-            'And for dates see:',
-            DATE_FORMAT_LINK,
-            'We add one item to d3\'s date formatter: *%{n}f* for fractional seconds',
-            'with n digits. For example, *2016-10-13 09:15:23.456* with tickformat',
-            '*%H~%M~%S.%2f* would display *09~15~23.46*'
-        ].join(' ')
+        description: descriptionWithDates('hover text')
     },
     // lines and grids
     showline: {

src/traces/bar/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var scatterAttrs = require('../scatter/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var colorScaleAttrs = require('../../components/colorscale/attributes');

src/traces/box/attributes.js

@@ -3,7 +3,7 @@
 var scatterAttrs = require('../scatter/attributes');
 var barAttrs = require('../bar/attributes');
 var colorAttrs = require('../../components/color/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var extendFlat = require('../../lib/extend').extendFlat;
 

src/traces/candlestick/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var extendFlat = require('../../lib').extendFlat;
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var OHLCattrs = require('../ohlc/attributes');
 var boxAttrs = require('../box/attributes');
 

src/traces/carpet/axis_attributes.js

@@ -3,12 +3,9 @@
 var fontAttrs = require('../../plots/font_attributes');
 var colorAttrs = require('../../components/color/attributes');
 var axesAttrs = require('../../plots/cartesian/layout_attributes');
+var descriptionWithDates = require('../../plots/cartesian/axis_format_attributes').descriptionWithDates;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
 
-var docs = require('../../constants/docs');
-var FORMAT_LINK = docs.FORMAT_LINK;
-var DATE_FORMAT_LINK = docs.DATE_FORMAT_LINK;
-
 module.exports = {
     color: {
         valType: 'color',
@@ -279,16 +276,7 @@ module.exports = {
         valType: 'string',
         dflt: '',
         editType: 'calc',
-        description: [
-            'Sets the tick label formatting rule using d3 formatting mini-languages',
-            'which are very similar to those in Python. For numbers, see:',
-            FORMAT_LINK,
-            'And for dates see:',
-            DATE_FORMAT_LINK,
-            'We add one item to d3\'s date formatter: *%{n}f* for fractional seconds',
-            'with n digits. For example, *2016-10-13 09:15:23.456* with tickformat',
-            '*%H~%M~%S.%2f* would display *09~15~23.46*'
-        ].join(' ')
+        description: descriptionWithDates('tick label')
     },
     tickformatstops: overrideAll(axesAttrs.tickformatstops, 'calc', 'from-root'),
     categoryorder: {

src/traces/cone/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var mesh3dAttrs = require('../mesh3d/attributes');
 var baseAttrs = require('../../plots/attributes');

src/traces/contour/attributes.js

@@ -2,7 +2,9 @@
 
 var heatmapAttrs = require('../heatmap/attributes');
 var scatterAttrs = require('../scatter/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisFormat = require('../../plots/cartesian/axis_format_attributes');
+var axisHoverFormat = axisFormat.axisHoverFormat;
+var descriptionOnlyNumbers = axisFormat.descriptionOnlyNumbers;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 var dash = require('../../components/drawing/attributes').dash;
 var fontAttrs = require('../../plots/font_attributes');
@@ -12,7 +14,6 @@ var filterOps = require('../../constants/filter_ops');
 var COMPARISON_OPS2 = filterOps.COMPARISON_OPS2;
 var INTERVAL_OPS = filterOps.INTERVAL_OPS;
 
-var FORMAT_LINK = require('../../constants/docs').FORMAT_LINK;
 
 var scatterLineAttrs = scatterAttrs.line;
 
@@ -181,11 +182,7 @@ module.exports = extendFlat({
             valType: 'string',
             dflt: '',
             editType: 'plot',
-            description: [
-                'Sets the contour label formatting rule using d3 formatting',
-                'mini-language which is very similar to Python, see:',
-                FORMAT_LINK
-            ].join(' ')
+            description: descriptionOnlyNumbers('contour label')
         },
         operation: {
             valType: 'enumerated',

src/traces/funnel/attributes.js

@@ -3,7 +3,7 @@
 var barAttrs = require('../bar/attributes');
 var lineAttrs = require('../scatter/attributes').line;
 var baseAttrs = require('../../plots/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var constants = require('./constants');

src/traces/heatmap/attributes.js

@@ -2,7 +2,7 @@
 
 var scatterAttrs = require('../scatter/attributes');
 var baseAttrs = require('../../plots/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 

src/traces/histogram/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var barAttrs = require('../bar/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var makeBinAttrs = require('./bin_attributes');
 var constants = require('./constants');

src/traces/histogram2d/attributes.js

@@ -4,7 +4,7 @@ var histogramAttrs = require('../histogram/attributes');
 var makeBinAttrs = require('../histogram/bin_attributes');
 var heatmapAttrs = require('../heatmap/attributes');
 var baseAttrs = require('../../plots/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 

src/traces/histogram2dcontour/attributes.js

@@ -3,7 +3,7 @@
 var histogram2dAttrs = require('../histogram2d/attributes');
 var contourAttrs = require('../contour/attributes');
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 
 var extendFlat = require('../../lib/extend').extendFlat;
 

src/traces/indicator/attributes.js

@@ -9,7 +9,7 @@ var domainAttrs = require('../../plots/domain').attributes;
 var axesAttrs = require('../../plots/cartesian/layout_attributes');
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
 var delta = require('../../constants/delta.js');
-var FORMAT_LINK = require('../../constants/docs').FORMAT_LINK;
+var descriptionOnlyNumbers = require('../../plots/cartesian/axis_format_attributes').descriptionOnlyNumbers;
 
 var textFontAttrs = fontAttrs({
     editType: 'plot',
@@ -147,11 +147,7 @@ module.exports = {
             valType: 'string',
             dflt: '',
             editType: 'plot',
-            description: [
-                'Sets the value formatting rule using d3 formatting mini-language',
-                'which is similar to those of Python. See',
-                FORMAT_LINK
-            ].join(' ')
+            description: descriptionOnlyNumbers('value')
         },
         font: extendFlat({}, textFontAttrs, {
             description: [
@@ -205,11 +201,7 @@ module.exports = {
         valueformat: {
             valType: 'string',
             editType: 'plot',
-            description: [
-                'Sets the value formatting rule using d3 formatting mini-language',
-                'which is similar to those of Python. See',
-                FORMAT_LINK
-            ].join(' ')
+            description: descriptionOnlyNumbers('value')
         },
         increasing: {
             symbol: {

src/traces/isosurface/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var meshAttrs = require('../mesh3d/attributes');
 var baseAttrs = require('../../plots/attributes');

src/traces/mesh3d/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var surfaceAttrs = require('../surface/attributes');
 var baseAttrs = require('../../plots/attributes');

src/traces/ohlc/attributes.js

@@ -2,7 +2,7 @@
 
 var extendFlat = require('../../lib').extendFlat;
 var scatterAttrs = require('../scatter/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var dash = require('../../components/drawing/attributes').dash;
 var fxAttrs = require('../../components/fx/attributes');
 var delta = require('../../constants/delta.js');

src/traces/sankey/attributes.js

@@ -8,12 +8,11 @@ var domainAttrs = require('../../plots/domain').attributes;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var colorAttributes = require('../../components/colorscale/attributes');
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
+var descriptionOnlyNumbers = require('../../plots/cartesian/axis_format_attributes').descriptionOnlyNumbers;
 
 var extendFlat = require('../../lib/extend').extendFlat;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
 
-var FORMAT_LINK = require('../../constants/docs').FORMAT_LINK;
-
 var attrs = module.exports = overrideAll({
     hoverinfo: extendFlat({}, baseAttrs.hoverinfo, {
         flags: [],
@@ -39,11 +38,7 @@ var attrs = module.exports = overrideAll({
     valueformat: {
         valType: 'string',
         dflt: '.3s',
-        description: [
-            'Sets the value formatting rule using d3 formatting mini-language',
-            'which is similar to those of Python. See',
-            FORMAT_LINK
-        ].join(' ')
+        description: descriptionOnlyNumbers('value')
     },
 
     valuesuffix: {

src/traces/scatter/attributes.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var colorScaleAttrs = require('../../components/colorscale/attributes');

src/traces/scatter3d/attributes.js

@@ -2,7 +2,7 @@
 
 var scatterAttrs = require('../scatter/attributes');
 var colorAttributes = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var baseAttrs = require('../../plots/attributes');

src/traces/scattergl/attributes.js

@@ -2,7 +2,7 @@
 
 var baseAttrs = require('../../plots/attributes');
 var scatterAttrs = require('../scatter/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 
 var extendFlat = require('../../lib/extend').extendFlat;

src/traces/splom/attributes.js

@@ -2,7 +2,7 @@
 
 var scatterAttrs = require('../scatter/attributes');
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var scatterGlAttrs = require('../scattergl/attributes');
 var cartesianIdRegex = require('../../plots/cartesian/constants').idRegex;

src/traces/streamtube/attributes.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var mesh3dAttrs = require('../mesh3d/attributes');
 var baseAttrs = require('../../plots/attributes');

src/traces/surface/attributes.js

@@ -2,7 +2,7 @@
 
 var Color = require('../../components/color');
 var colorScaleAttrs = require('../../components/colorscale/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var baseAttrs = require('../../plots/attributes');
 

src/traces/table/attributes.js

@@ -5,8 +5,7 @@ var extendFlat = require('../../lib/extend').extendFlat;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
 var fontAttrs = require('../../plots/font_attributes');
 var domainAttrs = require('../../plots/domain').attributes;
-
-var FORMAT_LINK = require('../../constants/docs').FORMAT_LINK;
+var descriptionOnlyNumbers = require('../../plots/cartesian/axis_format_attributes').descriptionOnlyNumbers;
 
 var attrs = module.exports = overrideAll({
     domain: domainAttrs({name: 'table', trace: true}),
@@ -45,11 +44,7 @@ var attrs = module.exports = overrideAll({
         format: {
             valType: 'data_array',
             dflt: [],
-            description: [
-                'Sets the cell value formatting rule using d3 formatting mini-language',
-                'which is similar to those of Python. See',
-                FORMAT_LINK
-            ].join(' ')
+            description: descriptionOnlyNumbers('cell value')
         },
 
         prefix: {
@@ -117,11 +112,7 @@ var attrs = module.exports = overrideAll({
         format: {
             valType: 'data_array',
             dflt: [],
-            description: [
-                'Sets the cell value formatting rule using d3 formatting mini-language',
-                'which is similar to those of Python. See',
-                FORMAT_LINK
-            ].join(' ')
+            description: descriptionOnlyNumbers('cell value')
         },
 
         prefix: {

src/traces/violin/attributes.js

@@ -2,7 +2,7 @@
 
 var boxAttrs = require('../box/attributes');
 var extendFlat = require('../../lib/extend').extendFlat;
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 
 module.exports = {
     y: boxAttrs.y,

src/traces/waterfall/attributes.js

@@ -3,7 +3,7 @@
 var barAttrs = require('../bar/attributes');
 var lineAttrs = require('../scatter/attributes').line;
 var baseAttrs = require('../../plots/attributes');
-var axisHoverFormat = require('../../plots/hoverformat_attributes');
+var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var constants = require('./constants');

test/image/mocks/period_positioning9.json

@@ -0,0 +1,33 @@
+{
+    "data": [
+        {
+            "xperiod": "M6",
+            "name": "Half year",
+            "type": "bar",
+            "y": [1, 2, 3, 4, 5, 6],
+            "x": ["2001-01", "2001-07", "2002-01", "2002-07", "2003-01", "2003-07"],
+            "texttemplate": "%{x}",
+            "textangle": 0
+        }
+    ],
+    "layout": {
+        "title": {
+            "text": "half-year periods and tickformat"
+        },
+        "width": 400,
+        "height": 300,
+        "margin": {
+            "t": 50,
+            "b": 50,
+            "l": 25,
+            "r": 25
+        },
+
+        "xaxis": {
+            "dtick": "M6",
+            "tickformat": "%Y H%h",
+            "ticklabelmode": "period",
+            "tickcolor": "black"
+        }
+    }
+}