IAM: Add routing header to method metadata, format docstrings, update docs configuration (via synth).

iam/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",
 ]
 
@@ -47,10 +48,14 @@
 # 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'
@@ -120,12 +125,20 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+html_theme = "alabaster"
 
 # 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 +227,17 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = "google-cloud-iam-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 = {
@@ -304,6 +328,16 @@
 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

iam/google/cloud/iam_credentials_v1/gapic/iam_credentials_client.py

@@ -22,6 +22,7 @@
 import google.api_core.gapic_v1.client_info
 import google.api_core.gapic_v1.config
 import google.api_core.gapic_v1.method
+import google.api_core.gapic_v1.routing_header
 import google.api_core.grpc_helpers
 import google.api_core.path_template
 import grpc
@@ -267,6 +268,19 @@ def generate_access_token(
         request = common_pb2.GenerateAccessTokenRequest(
             name=name, scope=scope, delegates=delegates, lifetime=lifetime
         )
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("name", name)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
         return self._inner_api_calls["generate_access_token"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
@@ -349,6 +363,19 @@ def generate_id_token(
             delegates=delegates,
             include_email=include_email,
         )
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("name", name)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
         return self._inner_api_calls["generate_id_token"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
@@ -424,6 +451,19 @@ def sign_blob(
         request = common_pb2.SignBlobRequest(
             name=name, payload=payload, delegates=delegates
         )
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("name", name)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
         return self._inner_api_calls["sign_blob"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
@@ -499,6 +539,19 @@ def sign_jwt(
         request = common_pb2.SignJwtRequest(
             name=name, payload=payload, delegates=delegates
         )
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("name", name)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
         return self._inner_api_calls["sign_jwt"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
@@ -543,20 +596,25 @@ def generate_identity_binding_access_token(
                 (https://tools.ietf.org/html/rfc7523) and must have 'kid' field in the
                 header. Supported signing algorithms: RS256 (RS512, ES256, ES512 coming
                 soon). Mandatory payload fields (along the lines of RFC 7523, section
-                3): - iss: issuer of the token. Must provide a discovery document at
-                $iss/.well-known/openid-configuration . The document needs to be
-                formatted according to section 4.2 of the OpenID Connect Discovery 1.0
-                specification. - iat: Issue time in seconds since epoch. Must be in the
-                past. - exp: Expiration time in seconds since epoch. Must be less than
-                48 hours after iat. We recommend to create tokens that last shorter than
-                6 hours to improve security unless business reasons mandate longer
-                expiration times. Shorter token lifetimes are generally more secure
-                since tokens that have been exfiltrated by attackers can be used for a
-                shorter time. you can configure the maximum lifetime of the incoming
-                token in the configuration of the mapper. The resulting Google token
-                will expire within an hour or at "exp", whichever is earlier. - sub: JWT
-                subject, identity asserted in the JWT. - aud: Configured in the mapper
-                policy. By default the service account email.
+                3):
+
+                -  iss: issuer of the token. Must provide a discovery document at
+                   $iss/.well-known/openid-configuration . The document needs to be
+                   formatted according to section 4.2 of the OpenID Connect Discovery
+                   1.0 specification.
+                -  iat: Issue time in seconds since epoch. Must be in the past.
+                -  exp: Expiration time in seconds since epoch. Must be less than 48
+                   hours after iat. We recommend to create tokens that last shorter than
+                   6 hours to improve security unless business reasons mandate longer
+                   expiration times. Shorter token lifetimes are generally more secure
+                   since tokens that have been exfiltrated by attackers can be used for
+                   a shorter time. you can configure the maximum lifetime of the
+                   incoming token in the configuration of the mapper. The resulting
+                   Google token will expire within an hour or at "exp", whichever is
+                   earlier.
+                -  sub: JWT subject, identity asserted in the JWT.
+                -  aud: Configured in the mapper policy. By default the service account
+                   email.
 
                 Claims from the incoming token can be transferred into the output token
                 accoding to the mapper configuration. The outgoing claim size is
@@ -606,6 +664,19 @@ def generate_identity_binding_access_token(
         request = common_pb2.GenerateIdentityBindingAccessTokenRequest(
             name=name, scope=scope, jwt=jwt
         )
+        if metadata is None:
+            metadata = []
+        metadata = list(metadata)
+        try:
+            routing_header = [("name", name)]
+        except AttributeError:
+            pass
+        else:
+            routing_metadata = google.api_core.gapic_v1.routing_header.to_grpc_metadata(
+                routing_header
+            )
+            metadata.append(routing_metadata)
+
         return self._inner_api_calls["generate_identity_binding_access_token"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )

iam/synth.metadata

@@ -1,19 +1,19 @@
 {
-  "updateTime": "2019-03-01T13:15:22.601913Z",
+  "updateTime": "2019-03-28T12:14:39.937996Z",
   "sources": [
     {
       "generator": {
         "name": "artman",
-        "version": "0.16.14",
-        "dockerImage": "googleapis/artman@sha256:f3d61ae45abaeefb6be5f228cda22732c2f1b00fb687c79c4bd4f2c42bb1e1a7"
+        "version": "0.16.20",
+        "dockerImage": "googleapis/artman@sha256:e3c054a2fb85a12481c722af616c7fb6f1d02d862248385eecbec3e4240ebd1e"
       }
     },
     {
       "git": {
         "name": "googleapis",
         "remote": "https://github.com/googleapis/googleapis.git",
-        "sha": "41d72d444fbe445f4da89e13be02078734fb7875",
-        "internalRef": "236230004"
+        "sha": "6a84b3267b0a95e922608b9891219075047eee29",
+        "internalRef": "240640999"
       }
     },
     {