docs: fix sphinx identifiers

.gitignore

@@ -45,6 +45,9 @@ htmlcov
 # JetBrains
 .idea
 
+# VS Code
+.vscode
+
 # Built documentation
 docs/_build
 docs/_build_doc2dash

gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2

@@ -188,7 +188,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             transport (Union[str, ~.{{ service.name }}Transport]): The
                 transport to use. If set to None, a transport is chosen
                 automatically.
-            client_options (client_options_lib.ClientOptions): Custom options for the
+            client_options (google.api_core.client_options.ClientOptions): Custom options for the
                 client. It won't take effect if a ``transport`` instance is provided.
                 (1) The ``api_endpoint`` property can be used to override the
                 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT

gapic/ads-templates/docs/_static/custom.css

@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    min-width: 100px
+}

gapic/ads-templates/docs/conf.py.j2

@@ -165,7 +165,7 @@ html_theme_options = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = []
+html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

gapic/schema/metadata.py

@@ -173,9 +173,23 @@ def python_import(self) -> imp.Import:
     @property
     def sphinx(self) -> str:
         """Return the Sphinx identifier for this type."""
-        if self.module:
-            return f'~.{self}'
-        return self.name
+
+        # Return std lib types right away
+        if not self.package:
+            return self
+
+        # Check if this is a 'google.protobuf' or 'google.rpc' type
+        # The output should look like: google.protobuf.timestamp_pb2.Timestamp
+        if self.proto_package.startswith("google.protobuf") or self.proto_package.startswith("google.rpc"):
+            return f"{self.proto_package}.{self.module}_pb2.{self.name}"
+
+        # Check if this is a library type
+        # Output should look like: google.cloud.vision_v1.types.FooBar
+        if self.proto_package.startswith(self.api_naming.proto_package):
+            package = self.api_naming.module_namespace + (
+                    self.api_naming.versioned_module_name,
+                ) + self.subpackage
+            return ".".join(package) + f".types.{self.name}"
 
     @property
     def subpackage(self) -> Tuple[str, ...]:

gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2

@@ -202,10 +202,10 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
                 credentials identify the application to the service; if none
                 are specified, the client will attempt to ascertain the
                 credentials from the environment.
-            transport (Union[str, ~.{{ service.name }}Transport]): The
+            transport (Union[str, {{ service.name }}Transport]): The
                 transport to use. If set to None, a transport is chosen
                 automatically.
-            client_options (client_options_lib.ClientOptions): Custom options for the
+            client_options (google.api_core.client_options.ClientOptions): Custom options for the
                 client. It won't take effect if a ``transport`` instance is provided.
                 (1) The ``api_endpoint`` property can be used to override the
                 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
@@ -322,18 +322,18 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
 
         Args:
             {%- if not method.client_streaming %}
-            request (:class:`{{ method.input.ident.sphinx }}`):
+            request ({{ method.input.ident.sphinx }}):
                 The request object.{{ ' ' -}}
                 {{ method.input.meta.doc|wrap(width=72, offset=36, indent=16) }}
             {% for key, field in method.flattened_fields.items() -%}
-            {{ field.name }} (:class:`{{ field.ident.sphinx }}`):
+            {{ field.name }} ({{ field.ident.sphinx }}):
                 {{ field.meta.doc|rst(width=72, indent=16, nl=False) }}
                 This corresponds to the ``{{ key }}`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
             {% endfor -%}
             {%- else %}
-            requests (Iterator[`{{ method.input.ident.sphinx }}`]):
+            requests (Iterator[{{ method.input.ident.sphinx }}]):
                 The request object iterator.{{ ' ' -}}
                 {{ method.input.meta.doc|wrap(width=72, offset=36, indent=16) }}
             {%- endif %}

gapic/templates/docs/_static/custom.css

@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    min-width: 100px
+}

gapic/templates/docs/conf.py.j2

@@ -347,6 +347,7 @@ intersphinx_mapping = {
     "grpc": ("https://grpc.io/grpc/python/", None),
     "requests": ("http://requests.kennethreitz.org/en/stable/", None),
     "proto": ("https://proto-plus-python.readthedocs.io/en/stable", None),
+    "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
 }
 
 

gapic/templates/noxfile.py.j2

@@ -2,6 +2,7 @@
 
 {% block content %}
 import os
+import shutil
 
 import nox  # type: ignore
 
@@ -37,4 +38,25 @@ def mypy(session):
         '{{ api.naming.versioned_module_name }}',
         {%- endif %}
     )
+
+@nox.session(python='3.6')
+def docs(session):
+    """Build the docs for this library."""
+
+    session.install("-e", ".")
+    session.install("sphinx<3.0.0", "alabaster", "recommonmark")
+
+    shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
+    session.run(
+        "sphinx-build",
+        "-W",  # warnings as errors
+        "-T",  # show full traceback on exception
+        "-N",  # no colors
+        "-b",
+        "html",
+        "-d",
+        os.path.join("docs", "_build", "doctrees", ""),
+        os.path.join("docs", ""),
+        os.path.join("docs", "_build", "html", ""),
+    )
 {% endblock %}