FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

fix: fix sphinx identifiers (#714) · googleapis/google-cloud-python@9f9e6b5 · GitHub

/ google-cloud-python Public

Commit 9f9e6b5

Browse files
busunkim96
authored
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)
1 parent 7b767f9 commit 9f9e6b5

18 files changed

Lines changed: 110 additions & 34 deletions

File tree

‎packages/gapic-generator/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ htmlcov
4545
# JetBrains
4646
.idea
4747

48+
# VS Code
49+
.vscode
50+
4851
# Built documentation
4952
docs/_build
5053
docs/_build_doc2dash

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
107107
kwargs: Additional arguments to pass to the constructor.
108108

109109
Returns:
110-
{@api.name}: The constructed client.
110+
{{ service.client_name }}: The constructed client.
111111
"""
112112
credentials = service_account.Credentials.from_service_account_info(info)
113113
kwargs["credentials"] = credentials
@@ -125,7 +125,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
125125
kwargs: Additional arguments to pass to the constructor.
126126

127127
Returns:
128-
{@api.name}: The constructed client.
128+
{{ service.client_name }}: The constructed client.
129129
"""
130130
credentials = service_account.Credentials.from_service_account_file(
131131
filename)
@@ -188,7 +188,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
188188
transport (Union[str, ~.{{ service.name }}Transport]): The
189189
transport to use. If set to None, a transport is chosen
190190
automatically.
191-
client_options (client_options_lib.ClientOptions): Custom options for the
191+
client_options (google.api_core.client_options.ClientOptions): Custom options for the
192192
client. It won't take effect if a ``transport`` instance is provided.
193193
(1) The ``api_endpoint`` property can be used to override the
194194
default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
@@ -306,7 +306,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
306306
{{ method.input.meta.doc|wrap(width=72, offset=36, indent=16) }}
307307
{% for key, field in method.flattened_fields.items() -%}
308308
{{ field.name }} (:class:`{{ field.ident.sphinx }}`):
309-
{{ field.meta.doc|rst(width=72, indent=16, nl=False) }}
309+
{{ field.meta.doc|rst(width=72, indent=16) }}
310310
This corresponds to the ``{{ key }}`` field
311311
on the ``request`` instance; if ``request`` is provided, this
312312
should not be set.
@@ -329,7 +329,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
329329
{%- else %}
330330
Iterable[{{ method.client_output.ident.sphinx }}]:
331331
{%- endif %}
332-
{{ method.client_output.meta.doc|rst(width=72, indent=16) }}
332+
{{ method.client_output.meta.doc|rst(width=72, indent=16, source_format='rst') }}
333333
{%- endif %}
334334
"""
335335
{%- if not method.client_streaming %}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ Types for {{ api.naming.long_name }} {{ api.naming.version }} API
33

44
.. automodule:: {{ api.naming.namespace|join('.')|lower }}.{{ api.naming.versioned_module_name }}.types
55
:members:
6+
:undoc-members:

‎packages/gapic-generator/gapic/ads-templates/docs/_static/custom.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
dl.field-list > dt {
2+
min-width: 100px
3+
}

‎packages/gapic-generator/gapic/ads-templates/docs/conf.py.j2‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ html_theme_options = {
165165
# Add any paths that contain custom static files (such as style sheets) here,
166166
# relative to this directory. They are copied after the builtin static files,
167167
# so a file named "default.css" will overwrite the builtin "default.css".
168-
# html_static_path = []
168+
html_static_path = ["_static"]
169169

170170
# Add any extra paths that contain custom files (such as robots.txt or
171171
# .htaccess) here, relative to this directory. These files are copied

‎packages/gapic-generator/gapic/schema/metadata.py‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,9 +173,22 @@ def python_import(self) -> imp.Import:
173173
@property
174174
def sphinx(self) -> str:
175175
"""Return the Sphinx identifier for this type."""
176-
if self.module:
177-
return f'~.{self}'
178-
return self.name
176+
177+
if not self.api_naming:
178+
if self.package:
179+
return '.'.join(self.package + (self.module, self.name))
180+
else:
181+
return str(self)
182+
183+
# Check if this is a generated type
184+
# Use the original module name rather than the module_alias
185+
if self.proto_package.startswith(self.api_naming.proto_package):
186+
return '.'.join(self.api_naming.module_namespace + (
187+
self.api_naming.versioned_module_name,
188+
) + self.subpackage + ('types',) + self.parent + (self.name, ))
189+
190+
# Anything left is a standard _pb2 type
191+
return f'{self.proto_package}.{self.module}_pb2.{self.name}'
179192

180193
@property
181194
def subpackage(self) -> Tuple[str, ...]:

‎packages/gapic-generator/gapic/schema/wrappers.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -690,7 +690,7 @@ def _client_output(self, enable_asyncio: bool):
690690
documentation=utils.doc(
691691
'An object representing a long-running operation. \n\n'
692692
'The result type for the operation will be '
693-
':class:`{ident}`: {doc}'.format(
693+
':class:`{ident}` {doc}'.format(
694694
doc=self.lro.response_type.meta.doc,
695695
ident=self.lro.response_type.ident.sphinx,
696696
),

‎packages/gapic-generator/gapic/templates/%namespace/%name_%version/%sub/services/%service/async_client.py.j2‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ class {{ service.async_client_name }}:
140140
{{ method.input.meta.doc|wrap(width=72, offset=36, indent=16) }}
141141
{% for key, field in method.flattened_fields.items() -%}
142142
{{ field.name }} (:class:`{{ field.ident.sphinx }}`):
143-
{{ field.meta.doc|rst(width=72, indent=16, nl=False) }}
143+
{{ field.meta.doc|rst(width=72, indent=16) }}
144144
This corresponds to the ``{{ key }}`` field
145145
on the ``request`` instance; if ``request`` is provided, this
146146
should not be set.
@@ -163,7 +163,7 @@ class {{ service.async_client_name }}:
163163
{%- else %}
164164
AsyncIterable[{{ method.client_output_async.ident.sphinx }}]:
165165
{%- endif %}
166-
{{ method.client_output_async.meta.doc|rst(width=72, indent=16) }}
166+
{{ method.client_output_async.meta.doc|rst(width=72, indent=16, source_format='rst') }}
167167
{%- endif %}
168168
"""
169169
{%- if not method.client_streaming %}

‎packages/gapic-generator/gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
123123
kwargs: Additional arguments to pass to the constructor.
124124

125125
Returns:
126-
{@api.name}: The constructed client.
126+
{{ service.client_name }}: The constructed client.
127127
"""
128128
credentials = service_account.Credentials.from_service_account_info(info)
129129
kwargs["credentials"] = credentials
@@ -141,7 +141,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
141141
kwargs: Additional arguments to pass to the constructor.
142142

143143
Returns:
144-
{@api.name}: The constructed client.
144+
{{ service.client_name }}: The constructed client.
145145
"""
146146
credentials = service_account.Credentials.from_service_account_file(
147147
filename)
@@ -202,10 +202,10 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
202202
credentials identify the application to the service; if none
203203
are specified, the client will attempt to ascertain the
204204
credentials from the environment.
205-
transport (Union[str, ~.{{ service.name }}Transport]): The
205+
transport (Union[str, {{ service.name }}Transport]): The
206206
transport to use. If set to None, a transport is chosen
207207
automatically.
208-
client_options (client_options_lib.ClientOptions): Custom options for the
208+
client_options (google.api_core.client_options.ClientOptions): Custom options for the
209209
client. It won't take effect if a ``transport`` instance is provided.
210210
(1) The ``api_endpoint`` property can be used to override the
211211
default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
@@ -322,18 +322,18 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
322322

323323
Args:
324324
{%- if not method.client_streaming %}
325-
request (:class:`{{ method.input.ident.sphinx }}`):
325+
request ({{ method.input.ident.sphinx }}):
326326
The request object.{{ ' ' -}}
327327
{{ method.input.meta.doc|wrap(width=72, offset=36, indent=16) }}
328328
{% for key, field in method.flattened_fields.items() -%}
329-
{{ field.name }} (:class:`{{ field.ident.sphinx }}`):
330-
{{ field.meta.doc|rst(width=72, indent=16, nl=False) }}
329+
{{ field.name }} ({{ field.ident.sphinx }}):
330+
{{ field.meta.doc|rst(width=72, indent=16) }}
331331
This corresponds to the ``{{ key }}`` field
332332
on the ``request`` instance; if ``request`` is provided, this
333333
should not be set.
334334
{% endfor -%}
335335
{%- else %}
336-
requests (Iterator[`{{ method.input.ident.sphinx }}`]):
336+
requests (Iterator[{{ method.input.ident.sphinx }}]):
337337
The request object iterator.{{ ' ' -}}
338338
{{ method.input.meta.doc|wrap(width=72, offset=36, indent=16) }}
339339
{%- endif %}
@@ -350,7 +350,7 @@ class {{ service.client_name }}(metaclass={{ service.client_name }}Meta):
350350
{%- else %}
351351
Iterable[{{ method.client_output.ident.sphinx }}]:
352352
{%- endif %}
353-
{{ method.client_output.meta.doc|rst(width=72, indent=16) }}
353+
{{ method.client_output.meta.doc|rst(width=72, indent=16, source_format='rst') }}
354354
{%- endif %}
355355
"""
356356
{%- if not method.client_streaming %}

‎packages/gapic-generator/gapic/templates/%namespace/%name_%version/%sub/services/%service/pagers.py.j2‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,9 @@ class {{ method.name }}Pager:
4545
Args:
4646
method (Callable): The method that was originally called, and
4747
which instantiated this pager.
48-
request (:class:`{{ method.input.ident.sphinx }}`):
48+
request ({{ method.input.ident.sphinx }}):
4949
The initial request object.
50-
response (:class:`{{ method.output.ident.sphinx }}`):
50+
response ({{ method.output.ident.sphinx }}):
5151
The initial response object.
5252
metadata (Sequence[Tuple[str, str]]): Strings which should be
5353
sent along with the request as metadata.
@@ -104,9 +104,9 @@ class {{ method.name }}AsyncPager:
104104
Args:
105105
method (Callable): The method that was originally called, and
106106
which instantiated this pager.
107-
request (:class:`{{ method.input.ident.sphinx }}`):
107+
request ({{ method.input.ident.sphinx }}):
108108
The initial request object.
109-
response (:class:`{{ method.output.ident.sphinx }}`):
109+
response ({{ method.output.ident.sphinx }}):
110110
The initial response object.
111111
metadata (Sequence[Tuple[str, str]]): Strings which should be
112112
sent along with the request as metadata.

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL