Add the tensorboard.summary public entry point

Summary:
Resolves #561.

Test Plan:
Ran the `build_pip_package.sh` script to build the Python 2 package,
then created a new Python 2 virtualenv in which I installed only the
latest nightly TensorFlow release (2017-09-22) and the generated wheel.
Then wrote
```py
import tensorflow as tf
from tensorboard import summary
result = tf.Session().run(summary.scalar('shelby', tf.constant(3)))
s = tf.Summary()
s.ParseFromString(result)
print(s)
```
and verified that the result was a proper scalar summary.

I then repeated the process using `pip install tensorflow==1.3.0`
instead of the nightly version to ensure that the module works for
normal TensorFlow users. (Note: the audio summary will not work because
TensorFlow 1.3 lacks 22730fd4c633a74e59c03ff76dc92e6ae2d5d020. This is
fine; users can continue to use the old API for that one.)

wchargin-branch: summary-module

Author: wchargin

tensorboard/BUILD

@@ -261,6 +261,32 @@ py_test(
     ],
 )
 
+py_library(
+    name = "summary",
+    srcs = ["summary.py"],
+    srcs_version = "PY2AND3",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//tensorboard/plugins/audio:summary",
+        "//tensorboard/plugins/histogram:summary",
+        "//tensorboard/plugins/image:summary",
+        "//tensorboard/plugins/pr_curve:summary",
+        "//tensorboard/plugins/scalar:summary",
+        "//tensorboard/plugins/text:summary",
+    ],
+)
+
+py_test(
+    name = "summary_test",
+    size = "small",
+    srcs = ["summary_test.py"],
+    srcs_version = "PY2AND3",
+    deps = [
+        ":summary",
+        "//tensorboard:expect_tensorflow_installed",
+    ],
+)
+
 py_library(
     name = "test_util",
     testonly = 1,

tensorboard/pip_package/BUILD

@@ -26,5 +26,6 @@ sh_binary(
           "setup.py",
           "//tensorboard",
           "//tensorboard:version",
+          "//tensorboard:summary",
         ],
 )

tensorboard/summary.py

@@ -0,0 +1,48 @@
+# Copyright 2017 The TensorFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Central API entry point for summary operations.
+
+This module simply offers a shorter way to access the members of modules
+like `tensorboard.plugins.scalar.summary`.
+"""
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+from tensorboard.plugins.audio import summary as _audio_summary
+from tensorboard.plugins.histogram import summary as _histogram_summary
+from tensorboard.plugins.image import summary as _image_summary
+from tensorboard.plugins.pr_curve import summary as _pr_curve_summary
+from tensorboard.plugins.scalar import summary as _scalar_summary
+from tensorboard.plugins.text import summary as _text_summary
+
+
+audio = _audio_summary.op
+audio_pb = _audio_summary.pb
+
+histogram = _histogram_summary.op
+histogram_pb = _histogram_summary.pb
+
+image = _image_summary.op
+image_pb = _image_summary.pb
+
+pr_curve = _pr_curve_summary.op
+pr_curve_raw_data = _pr_curve_summary.raw_data_op
+
+scalar = _scalar_summary.op
+scalar_pb = _scalar_summary.pb
+
+text = _text_summary.op
+text_pb = _text_summary.pb

tensorboard/summary_test.py

@@ -0,0 +1,81 @@
+# Copyright 2017 The TensorFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""API tests for the `tensorboard.summary` module.
+
+These tests are especially important because this module is the standard
+public entry point for end users, so we should be as careful as possible
+to ensure that we export the right things.
+"""
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import collections
+
+import tensorflow as tf
+from tensorboard import summary
+
+
+STANDARD_PLUGINS = frozenset([
+    'audio',
+    'histogram',
+    'image',
+    'pr_curve',
+    'scalar',
+    'text',
+])
+
+# The subset of `STANDARD_PLUGINS` for which we do not currently have
+# functions to generate a summary protobuf outside of a TensorFlow
+# graph. This set should ideally be empty; any entries here should be
+# considered temporary.
+PLUGINS_WITHOUT_PB_FUNCTIONS = frozenset([
+    'pr_curve',  # TODO(@chihuahua, #445): Fix this.
+])
+
+
+class SummaryExportsTest(tf.test.TestCase):
+
+  def test_each_plugin_has_an_export(self):
+    for plugin in STANDARD_PLUGINS:
+      self.assertIsInstance(getattr(summary, plugin), collections.Callable)
+
+  def test_plugins_export_pb_functions(self):
+    for plugin in STANDARD_PLUGINS:
+      if plugin not in PLUGINS_WITHOUT_PB_FUNCTIONS:
+        self.assertIsInstance(
+            getattr(summary, '%s_pb' % plugin), collections.Callable)
+
+  def test_all_exports_correspond_to_plugins(self):
+    exports = [name for name in dir(summary) if not name.startswith('_')]
+    futures = frozenset(('absolute_import', 'division', 'print_function'))
+    bad_exports = [
+        name for name in exports
+        if name not in futures and not any(
+            name == plugin or name.startswith('%s_' % plugin)
+            for plugin in STANDARD_PLUGINS)
+    ]
+    if bad_exports:
+      self.fail(
+          'The following exports do not correspond to known standard '
+          'plugins: %r. Please mark these as private by prepending an '
+          'underscore to their names, or, if they correspond to a new '
+          'plugin that you are certain should be part of the public API '
+          'forever, add that plugin to the STANDARD_PLUGINS set in this '
+          'module.' % bad_exports)
+
+
+if __name__ == '__main__':
+  tf.test.main()