AutoML: add proto files; add 'docs' session to 'nox'; update docstrings (via synth).

automl/docs/README.rst

@@ -0,0 +1 @@
+../README.rst

automl/docs/conf.py

@@ -25,7 +25,7 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
+needs_sphinx = "1.6.3"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -36,6 +36,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
     "sphinx.ext.viewcode",
 ]
 
@@ -44,13 +45,18 @@
 autodoc_default_flags = ["members"]
 autosummary_generate = True
 
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# Allow markdown includes (so releases.md can include CHANGLEOG.md)
+# http://www.sphinx-doc.org/en/master/markdown.html
+source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -116,6 +122,7 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -125,7 +132,15 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "description": "Google Cloud Client Libraries for Python",
+    "github_user": "googleapis",
+    "github_repo": "google-cloud-python",
+    "github_banner": True,
+    "font_family": "'Roboto', Georgia, sans",
+    "head_font_family": "'Roboto', Georgia, serif",
+    "code_font_family": "'Roboto Mono', 'Consolas', monospace",
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -214,6 +229,18 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = "google-cloud-automl-doc"
 
+# -- Options for warnings ------------------------------------------------------
+
+
+suppress_warnings = [
+    # Temporarily suppress this to avoid "more than one target found for
+    # cross-reference" warning, which are intractable for us to avoid while in
+    # a mono-repo.
+    # See https://github.com/sphinx-doc/sphinx/blob
+    # /2a65ffeef5c107c19084fabdd706cdff3f52d93c/sphinx/domains/python.py#L843
+    "ref.python"
+]
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -260,6 +287,7 @@
 # If false, no module index is generated.
 # latex_domain_indices = True
 
+
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
@@ -277,6 +305,7 @@
 # If true, show URL addresses after external links.
 # man_show_urls = False
 
+
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
@@ -306,12 +335,24 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
 
+
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "python": ("http://python.readthedocs.org/en/latest/", None),
     "gax": ("https://gax-python.readthedocs.org/en/latest/", None),
+    "google-auth": ("https://google-auth.readthedocs.io/en/stable", None),
+    "google-gax": ("https://gax-python.readthedocs.io/en/latest/", None),
+    "google.api_core": (
+        "https://googleapis.github.io/google-cloud-python/latest",
+        None,
+    ),
+    "grpc": ("https://grpc.io/grpc/python/", None),
+    "requests": ("http://docs.python-requests.org/en/master/", None),
+    "fastavro": ("https://fastavro.readthedocs.io/en/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
 }
 
+
 # Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True

automl/docs/index.rst

@@ -1,4 +1,4 @@
-.. include:: /../automl/README.rst
+.. include:: README.rst
 
 
 Api Reference
@@ -13,7 +13,7 @@ Api Reference
 Changelog
 ---------
 
-For a list of all ``google-cloud-datastore`` releases:
+For a list of all ``google-cloud-automl`` releases:
 
 .. toctree::
   :maxdepth: 2

automl/google/cloud/automl_v1beta1/gapic/auto_ml_client.py

@@ -98,12 +98,26 @@ def from_service_account_file(cls, filename, *args, **kwargs):
     from_service_account_json = from_service_account_file
 
     @classmethod
-    def location_path(cls, project, location):
-        """Return a fully-qualified location string."""
+    def annotation_spec_path(cls, project, location, dataset, annotation_spec):
+        """Return a fully-qualified annotation_spec string."""
         return google.api_core.path_template.expand(
-            "projects/{project}/locations/{location}",
+            "projects/{project}/locations/{location}/datasets/{dataset}/annotationSpecs/{annotation_spec}",
+            project=project,
+            location=location,
+            dataset=dataset,
+            annotation_spec=annotation_spec,
+        )
+
+    @classmethod
+    def column_spec_path(cls, project, location, dataset, table_spec, column_spec):
+        """Return a fully-qualified column_spec string."""
+        return google.api_core.path_template.expand(
+            "projects/{project}/locations/{location}/datasets/{dataset}/tableSpecs/{table_spec}/columnSpecs/{column_spec}",
             project=project,
             location=location,
+            dataset=dataset,
+            table_spec=table_spec,
+            column_spec=column_spec,
         )
 
     @classmethod
@@ -116,6 +130,15 @@ def dataset_path(cls, project, location, dataset):
             dataset=dataset,
         )
 
+    @classmethod
+    def location_path(cls, project, location):
+        """Return a fully-qualified location string."""
+        return google.api_core.path_template.expand(
+            "projects/{project}/locations/{location}",
+            project=project,
+            location=location,
+        )
+
     @classmethod
     def model_path(cls, project, location, model):
         """Return a fully-qualified model string."""
@@ -137,17 +160,6 @@ def model_evaluation_path(cls, project, location, model, model_evaluation):
             model_evaluation=model_evaluation,
         )
 
-    @classmethod
-    def annotation_spec_path(cls, project, location, dataset, annotation_spec):
-        """Return a fully-qualified annotation_spec string."""
-        return google.api_core.path_template.expand(
-            "projects/{project}/locations/{location}/datasets/{dataset}/annotationSpecs/{annotation_spec}",
-            project=project,
-            location=location,
-            dataset=dataset,
-            annotation_spec=annotation_spec,
-        )
-
     @classmethod
     def table_spec_path(cls, project, location, dataset, table_spec):
         """Return a fully-qualified table_spec string."""
@@ -159,18 +171,6 @@ def table_spec_path(cls, project, location, dataset, table_spec):
             table_spec=table_spec,
         )
 
-    @classmethod
-    def column_spec_path(cls, project, location, dataset, table_spec, column_spec):
-        """Return a fully-qualified column_spec string."""
-        return google.api_core.path_template.expand(
-            "projects/{project}/locations/{location}/datasets/{dataset}/tableSpecs/{table_spec}/columnSpecs/{column_spec}",
-            project=project,
-            location=location,
-            dataset=dataset,
-            table_spec=table_spec,
-            column_spec=column_spec,
-        )
-
     def __init__(
         self,
         transport=None,

automl/google/cloud/automl_v1beta1/proto/annotation_payload.proto

@@ -0,0 +1,74 @@
+// Copyright 2018 Google LLC.
+//
+// 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.
+//
+
+syntax = "proto3";
+
+package google.cloud.automl.v1beta1;
+
+import "google/api/annotations.proto";
+import "google/cloud/automl/v1beta1/classification.proto";
+import "google/cloud/automl/v1beta1/detection.proto";
+import "google/cloud/automl/v1beta1/tables.proto";
+import "google/cloud/automl/v1beta1/text_extraction.proto";
+import "google/cloud/automl/v1beta1/text_sentiment.proto";
+import "google/cloud/automl/v1beta1/translation.proto";
+import "google/protobuf/any.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/cloud/automl/v1beta1;automl";
+option java_multiple_files = true;
+option java_package = "com.google.cloud.automl.v1beta1";
+option php_namespace = "Google\\Cloud\\AutoMl\\V1beta1";
+
+
+// Contains annotation information that is relevant to AutoML.
+message AnnotationPayload {
+  // Output only . Additional information about the annotation
+  // specific to the AutoML domain.
+  oneof detail {
+    // Annotation details for translation.
+    TranslationAnnotation translation = 2;
+
+    // Annotation details for content or image classification.
+    ClassificationAnnotation classification = 3;
+
+    // Annotation details for image object detection.
+    ImageObjectDetectionAnnotation image_object_detection = 4;
+
+    // Annotation details for video classification.
+    // Returned for Video Classification predictions.
+    VideoClassificationAnnotation video_classification = 9;
+
+    // Annotation details for text extraction.
+    TextExtractionAnnotation text_extraction = 6;
+
+    // Annotation details for text sentiment.
+    TextSentimentAnnotation text_sentiment = 7;
+
+    // Annotation details for Tables.
+    TablesAnnotation tables = 10;
+  }
+
+  // Output only . The resource ID of the annotation spec that
+  // this annotation pertains to. The annotation spec comes from either an
+  // ancestor dataset, or the dataset that was used to train the model in use.
+  string annotation_spec_id = 1;
+
+  // Output only. The value of [AnnotationSpec.display_name][google.cloud.automl.v1beta1.AnnotationSpec.display_name] when the model
+  // was trained. Because this field returns a value at model training time,
+  // for different models trained using the same dataset, the returned value
+  // could be different as model owner could update the display_name between
+  // any two model training.
+  string display_name = 5;
+}