fix: fix sphinx identifiers (#714)

Cross-references like `~.ImageAnnotatorClient` don't always work correctly with sphinx. This PR changes the `sphinx()` method to always produce a full path like `google.cloud.vision_v1.ImageAnnotatorClient`. 

Also some other smaller changes:
- Generate a separate `.rst` page for each service, which improves readability for APIs that have (1) a lot of services or (2) a lot of methods in a service. `services.rst` acts as an index page instead.
- Add pagers to the generated docs
- Use `undoc-members` to list enum attributes in generated docs (fixes #625) 
- Add newlines after bulleted lists by removing `nl=False`. Fixes #604 
- Add a 'docs' session to the templated `noxfile.py` so folks using the self-service model can have generated docs.
- Fix reference to LRO result type in `Returns:`
- Fix `{@api.name}` reference in the `from_service_account..`. methods  to reference the client type instead
- Remove `:class:` notation when specifying types for attributes (sphinx doesn't need it to create a link)

Author: busunkim96

.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

@@ -107,7 +107,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             kwargs: Additional arguments to pass to the constructor.
 
         Returns:
-            {@api.name}: The constructed client.
+            {{ service.client_name }}: The constructed client.
         """
         credentials = service_account.Credentials.from_service_account_info(info)
         kwargs["credentials"] = credentials
@@ -125,7 +125,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             kwargs: Additional arguments to pass to the constructor.
 
         Returns:
-            {@api.name}: The constructed client.
+            {{ service.client_name }}: The constructed client.
         """
         credentials = service_account.Credentials.from_service_account_file(
             filename)
@@ -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
@@ -306,7 +306,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
                 {{ 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.meta.doc|rst(width=72, indent=16, nl=False) }}
+                {{ field.meta.doc|rst(width=72, indent=16) }}
                 This corresponds to the ``{{ key }}`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -329,7 +329,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             {%- else %}
             Iterable[{{ method.client_output.ident.sphinx }}]:
             {%- endif %}
-                {{ method.client_output.meta.doc|rst(width=72, indent=16) }}
+                {{ method.client_output.meta.doc|rst(width=72, indent=16, source_format='rst') }}
         {%- endif %}
         """
         {%- if not method.client_streaming %}

gapic/ads-templates/docs/%name_%version/types.rst.j2

@@ -3,3 +3,4 @@ Types for {{ api.naming.long_name }} {{ api.naming.version }} API
 
 .. automodule:: {{ api.naming.namespace|join('.')|lower }}.{{ api.naming.versioned_module_name }}.types
     :members:
+    :undoc-members:

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,22 @@ 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
+
+        if not self.api_naming:
+            if self.package:
+                return '.'.join(self.package + (self.module, self.name))
+            else:
+                return str(self)
+
+        # Check if this is a generated type
+        # Use the original module name rather than the module_alias
+        if self.proto_package.startswith(self.api_naming.proto_package):
+            return '.'.join(self.api_naming.module_namespace + (
+                self.api_naming.versioned_module_name,
+                ) + self.subpackage + ('types',) + self.parent + (self.name, ))
+
+        # Anything left is a standard _pb2 type
+        return f'{self.proto_package}.{self.module}_pb2.{self.name}'
 
     @property
     def subpackage(self) -> Tuple[str, ...]:

gapic/schema/wrappers.py

@@ -690,7 +690,7 @@ def _client_output(self, enable_asyncio: bool):
                 documentation=utils.doc(
                     'An object representing a long-running operation. \n\n'
                     'The result type for the operation will be '
-                    ':class:`{ident}`: {doc}'.format(
+                    ':class:`{ident}` {doc}'.format(
                         doc=self.lro.response_type.meta.doc,
                         ident=self.lro.response_type.ident.sphinx,
                     ),

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

@@ -140,7 +140,7 @@ class {{ service.async_client_name }}:
                 {{ 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.meta.doc|rst(width=72, indent=16, nl=False) }}
+                {{ field.meta.doc|rst(width=72, indent=16) }}
                 This corresponds to the ``{{ key }}`` field
                 on the ``request`` instance; if ``request`` is provided, this
                 should not be set.
@@ -163,7 +163,7 @@ class {{ service.async_client_name }}:
             {%- else %}
             AsyncIterable[{{ method.client_output_async.ident.sphinx }}]:
             {%- endif %}
-                {{ method.client_output_async.meta.doc|rst(width=72, indent=16) }}
+                {{ method.client_output_async.meta.doc|rst(width=72, indent=16, source_format='rst') }}
         {%- endif %}
         """
         {%- if not method.client_streaming %}

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

@@ -123,7 +123,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             kwargs: Additional arguments to pass to the constructor.
 
         Returns:
-            {@api.name}: The constructed client.
+            {{ service.client_name }}: The constructed client.
         """
         credentials = service_account.Credentials.from_service_account_info(info)
         kwargs["credentials"] = credentials
@@ -141,7 +141,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             kwargs: Additional arguments to pass to the constructor.
 
         Returns:
-            {@api.name}: The constructed client.
+            {{ service.client_name }}: The constructed client.
         """
         credentials = service_account.Credentials.from_service_account_file(
             filename)
@@ -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.meta.doc|rst(width=72, indent=16, nl=False) }}
+            {{ field.name }} ({{ field.ident.sphinx }}):
+                {{ field.meta.doc|rst(width=72, indent=16) }}
                 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 %}
@@ -350,7 +350,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
             {%- else %}
             Iterable[{{ method.client_output.ident.sphinx }}]:
             {%- endif %}
-                {{ method.client_output.meta.doc|rst(width=72, indent=16) }}
+                {{ method.client_output.meta.doc|rst(width=72, indent=16, source_format='rst') }}
         {%- endif %}
         """
         {%- if not method.client_streaming %}

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

@@ -45,9 +45,9 @@ class {{ method.name }}Pager:
         Args:
             method (Callable): The method that was originally called, and
                 which instantiated this pager.
-            request (:class:`{{ method.input.ident.sphinx }}`):
+            request ({{ method.input.ident.sphinx }}):
                 The initial request object.
-            response (:class:`{{ method.output.ident.sphinx }}`):
+            response ({{ method.output.ident.sphinx }}):
                 The initial response object.
             metadata (Sequence[Tuple[str, str]]): Strings which should be
                 sent along with the request as metadata.
@@ -104,9 +104,9 @@ class {{ method.name }}AsyncPager:
         Args:
             method (Callable): The method that was originally called, and
                 which instantiated this pager.
-            request (:class:`{{ method.input.ident.sphinx }}`):
+            request ({{ method.input.ident.sphinx }}):
                 The initial request object.
-            response (:class:`{{ method.output.ident.sphinx }}`):
+            response ({{ method.output.ident.sphinx }}):
                 The initial response object.
             metadata (Sequence[Tuple[str, str]]): Strings which should be
                 sent along with the request as metadata.