From 39be474b4419dfa521ef51927fd36dbf257d68e3 Mon Sep 17 00:00:00 2001
From: Bu Sun Kim <8822365+busunkim96@users.noreply.github.com>
Date: Tue, 22 Dec 2020 10:51:18 -0700
Subject: [PATCH 1/3] 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)
---
 .gitignore                                    |  3 +++
 .../%sub/services/%service/client.py.j2       | 10 ++++-----
 .../docs/%name_%version/types.rst.j2          |  1 +
 gapic/ads-templates/docs/_static/custom.css   |  3 +++
 gapic/ads-templates/docs/conf.py.j2           |  2 +-
 gapic/schema/metadata.py                      | 19 +++++++++++++---
 gapic/schema/wrappers.py                      |  2 +-
 .../%sub/services/%service/async_client.py.j2 |  4 ++--
 .../%sub/services/%service/client.py.j2       | 18 +++++++--------
 .../%sub/services/%service/pagers.py.j2       |  8 +++----
 .../docs/%name_%version/%service.rst.j2       | 12 ++++++++++
 .../docs/%name_%version/services.rst.j2       | 10 ++++-----
 .../docs/%name_%version/types.rst.j2          |  1 +
 gapic/templates/docs/_static/custom.css       |  3 +++
 gapic/templates/docs/conf.py.j2               |  3 ++-
 gapic/templates/noxfile.py.j2                 | 22 +++++++++++++++++++
 tests/unit/schema/wrappers/test_enums.py      |  2 +-
 tests/unit/schema/wrappers/test_message.py    | 21 ++++++++++++++++--
 18 files changed, 110 insertions(+), 34 deletions(-)
 create mode 100644 gapic/ads-templates/docs/_static/custom.css
 create mode 100644 gapic/templates/docs/%name_%version/%service.rst.j2
 create mode 100644 gapic/templates/docs/_static/custom.css

diff --git a/.gitignore b/.gitignore
index df28dce99d..5b68f2ed58 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,9 @@ htmlcov
 # JetBrains
 .idea
 
+# VS Code
+.vscode
+
 # Built documentation
 docs/_build
 docs/_build_doc2dash
diff --git a/gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2 b/gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2
index e3d0016a7a..4d2f0abebb 100644
--- a/gapic/ads-templates/%namespace/%name/%version/%sub/services/%service/client.py.j2
+++ b/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 %}
diff --git a/gapic/ads-templates/docs/%name_%version/types.rst.j2 b/gapic/ads-templates/docs/%name_%version/types.rst.j2
index 640641f211..a46bd12b22 100644
--- a/gapic/ads-templates/docs/%name_%version/types.rst.j2
+++ b/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:
diff --git a/gapic/ads-templates/docs/_static/custom.css b/gapic/ads-templates/docs/_static/custom.css
new file mode 100644
index 0000000000..c4e78bac63
--- /dev/null
+++ b/gapic/ads-templates/docs/_static/custom.css
@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    min-width: 100px
+}
\ No newline at end of file
diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2
index 1e827b37d9..1d60ece902 100644
--- a/gapic/ads-templates/docs/conf.py.j2
+++ b/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
diff --git a/gapic/schema/metadata.py b/gapic/schema/metadata.py
index cd96ab86c3..0276fe0989 100644
--- a/gapic/schema/metadata.py
+++ b/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, ...]:
diff --git a/gapic/schema/wrappers.py b/gapic/schema/wrappers.py
index 00f22d6da2..6020a26061 100644
--- a/gapic/schema/wrappers.py
+++ b/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,
                     ),
diff --git a/gapic/templates/%namespace/%name_%version/%sub/services/%service/async_client.py.j2 b/gapic/templates/%namespace/%name_%version/%sub/services/%service/async_client.py.j2
index 6354418f7f..f6e380d067 100644
--- a/gapic/templates/%namespace/%name_%version/%sub/services/%service/async_client.py.j2
+++ b/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 %}
diff --git a/gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2 b/gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2
index 6d703fb2de..21b0c9f201 100644
--- a/gapic/templates/%namespace/%name_%version/%sub/services/%service/client.py.j2
+++ b/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 %}
diff --git a/gapic/templates/%namespace/%name_%version/%sub/services/%service/pagers.py.j2 b/gapic/templates/%namespace/%name_%version/%sub/services/%service/pagers.py.j2
index 2f9598d2e3..ea08466ba0 100644
--- a/gapic/templates/%namespace/%name_%version/%sub/services/%service/pagers.py.j2
+++ b/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.
diff --git a/gapic/templates/docs/%name_%version/%service.rst.j2 b/gapic/templates/docs/%name_%version/%service.rst.j2
new file mode 100644
index 0000000000..6a54833b5a
--- /dev/null
+++ b/gapic/templates/docs/%name_%version/%service.rst.j2
@@ -0,0 +1,12 @@
+{{ service.name }}
+{{ '-' * (18 + service.name|length) }}
+
+.. automodule:: {{ (api.naming.module_namespace + (api.naming.versioned_module_name,) + service.meta.address.subpackage)|join(".") }}.services.{{ service.name|snake_case }}
+    :members:
+    :inherited-members:
+
+{% if service.has_pagers %}
+.. automodule:: {{ (api.naming.module_namespace + (api.naming.versioned_module_name,) + service.meta.address.subpackage)|join(".") }}.services.{{ service.name|snake_case }}.pagers
+    :members:
+    :inherited-members:
+{% endif %}
\ No newline at end of file
diff --git a/gapic/templates/docs/%name_%version/services.rst.j2 b/gapic/templates/docs/%name_%version/services.rst.j2
index b0f05d6931..98ba64f60f 100644
--- a/gapic/templates/docs/%name_%version/services.rst.j2
+++ b/gapic/templates/docs/%name_%version/services.rst.j2
@@ -1,8 +1,8 @@
 Services for {{ api.naming.long_name }} {{ api.naming.version }} API
 {{ '=' * (18 + api.naming.long_name|length + api.naming.version|length) }}
+.. toctree::
+    :maxdepth: 2
 
-{% for service in api.services.values()|sort(attribute='name') -%}
-.. automodule:: {{ (api.naming.module_namespace + (api.naming.versioned_module_name,) + service.meta.address.subpackage)|join(".") }}.services.{{ service.name|snake_case }}
-    :members:
-    :inherited-members:
-{% endfor %}
+    {% for service in api.services.values()|sort(attribute='name') -%}
+    {{ service.name|snake_case }}
+    {% endfor %}
diff --git a/gapic/templates/docs/%name_%version/types.rst.j2 b/gapic/templates/docs/%name_%version/types.rst.j2
index a77df003f7..2f453dd8cd 100644
--- a/gapic/templates/docs/%name_%version/types.rst.j2
+++ b/gapic/templates/docs/%name_%version/types.rst.j2
@@ -3,4 +3,5 @@ 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:
     :show-inheritance:
diff --git a/gapic/templates/docs/_static/custom.css b/gapic/templates/docs/_static/custom.css
new file mode 100644
index 0000000000..c4e78bac63
--- /dev/null
+++ b/gapic/templates/docs/_static/custom.css
@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    min-width: 100px
+}
\ No newline at end of file
diff --git a/gapic/templates/docs/conf.py.j2 b/gapic/templates/docs/conf.py.j2
index 423c3ad088..d4f1b215a6 100644
--- a/gapic/templates/docs/conf.py.j2
+++ b/gapic/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
@@ -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),
 }
 
 
diff --git a/gapic/templates/noxfile.py.j2 b/gapic/templates/noxfile.py.j2
index 5fde488f00..65397ea71c 100644
--- a/gapic/templates/noxfile.py.j2
+++ b/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 %}
diff --git a/tests/unit/schema/wrappers/test_enums.py b/tests/unit/schema/wrappers/test_enums.py
index 0602a09e9c..3debb5603b 100644
--- a/tests/unit/schema/wrappers/test_enums.py
+++ b/tests/unit/schema/wrappers/test_enums.py
@@ -39,4 +39,4 @@ def test_enum_value_properties():
 def test_enum_ident():
     message = make_enum('Baz', package='foo.v1', module='bar')
     assert str(message.ident) == 'bar.Baz'
-    assert message.ident.sphinx == '~.bar.Baz'
+    assert message.ident.sphinx == 'foo.v1.bar.Baz'
diff --git a/tests/unit/schema/wrappers/test_message.py b/tests/unit/schema/wrappers/test_message.py
index 7d8cca169a..4a7905d1b2 100644
--- a/tests/unit/schema/wrappers/test_message.py
+++ b/tests/unit/schema/wrappers/test_message.py
@@ -21,6 +21,7 @@
 from google.api import resource_pb2
 from google.protobuf import descriptor_pb2
 
+from gapic.schema import naming
 from gapic.schema import metadata
 from gapic.schema import wrappers
 
@@ -50,7 +51,7 @@ def test_message_docstring():
 def test_message_ident():
     message = make_message('Baz', package='foo.v1', module='bar')
     assert str(message.ident) == 'bar.Baz'
-    assert message.ident.sphinx == '~.bar.Baz'
+    assert message.ident.sphinx == 'foo.v1.bar.Baz'
 
 
 def test_message_ident_collisions():
@@ -58,7 +59,23 @@ def test_message_ident_collisions():
         collisions={'bar'},
     )
     assert str(message.ident) == 'fv_bar.Baz'
-    assert message.ident.sphinx == '~.fv_bar.Baz'
+    assert message.ident.sphinx == 'foo.v1.bar.Baz'
+
+
+def test_message_pb2_sphinx_ident():
+    meta = metadata.Metadata(
+        address=metadata.Address(
+            name='Timestamp',
+            package=('google', 'protobuf'),
+            module='timestamp',
+            api_naming=naming.NewNaming(
+                proto_package="foo.bar"
+            )
+        )
+    )
+    message = make_message("Timestamp", package='google.protobuf',
+        module='timestamp', meta=meta)
+    assert message.ident.sphinx == 'google.protobuf.timestamp_pb2.Timestamp'
 
 
 def test_get_field():

From 7c185e87cb4252b1f99ed121515814595f9492c4 Mon Sep 17 00:00:00 2001
From: Bu Sun Kim <8822365+busunkim96@users.noreply.github.com>
Date: Tue, 22 Dec 2020 11:08:03 -0700
Subject: [PATCH 2/3] feat: allow warehouse name to be customized (#717)

Allow warehouse name (package name in `setup.py`) to be customized via a CLI option.

This is a pretty common reason for a `synth.py` regex replace:
- One repo has more than one API (e.g., Bigtable and Bigtable Admin) but the package name should always be `google-cloud-bigtable`
- We want an extra `-` in the repo name and package name to make it easier to read and type. (`google-cloud-binaryauthorization` -> `google-cloud-binary-authorization`)
- Package name constructed from the namespace doesn't match the `google-cloud-{API}` convention (`google-cloud-devtools-containeranalysis` -> `google-cloud-containeranalysis`)

Fixes #605
---
 gapic/schema/naming.py               | 13 ++++++++++---
 gapic/utils/options.py               |  4 ++++
 tests/unit/generator/test_options.py |  5 +++++
 tests/unit/schema/test_naming.py     | 10 ++++++++++
 4 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/gapic/schema/naming.py b/gapic/schema/naming.py
index c591ad59cc..3f49a18a2e 100644
--- a/gapic/schema/naming.py
+++ b/gapic/schema/naming.py
@@ -42,6 +42,7 @@ class Naming(abc.ABC):
     version: str = ''
     product_name: str = ''
     proto_package: str = ''
+    _warehouse_package_name: str = ''
 
     def __post_init__(self):
         if not self.product_name:
@@ -141,6 +142,10 @@ def build(
                 # with ('x.y',) will become a two-tuple: ('x', 'y')
                 i.capitalize() for i in '.'.join(opts.namespace).split('.')
             ))
+        if opts.warehouse_package_name:
+            package_info = dataclasses.replace(package_info,
+                _warehouse_package_name=opts.warehouse_package_name
+                                               )
 
         # Done; return the naming information.
         return package_info
@@ -186,9 +191,11 @@ def versioned_module_name(self) -> str:
     @property
     def warehouse_package_name(self) -> str:
         """Return the appropriate Python package name for Warehouse."""
-
-        # Piece the name and namespace together to come up with the
-        # proper package name.
+        # If a custom name has been set, use it
+        if self._warehouse_package_name:
+            return self._warehouse_package_name
+        # Otherwise piece the name and namespace together to come
+        # up with the proper package name.
         answer = list(self.namespace) + self.name.split(' ')
         return '-'.join(answer).lower()
 
diff --git a/gapic/utils/options.py b/gapic/utils/options.py
index d99e34c631..b8e79a0601 100644
--- a/gapic/utils/options.py
+++ b/gapic/utils/options.py
@@ -34,6 +34,7 @@ class Options:
     """
     name: str = ''
     namespace: Tuple[str, ...] = dataclasses.field(default=())
+    warehouse_package_name: str = ''
     retry: Optional[Dict[str, Any]] = None
     sample_configs: Tuple[str, ...] = dataclasses.field(default=())
     templates: Tuple[str, ...] = dataclasses.field(default=('DEFAULT',))
@@ -53,6 +54,7 @@ class Options:
         'add-iam-methods',      # microgenerator implementation for `reroute_to_grpc_interface`
         # transport type(s) delineated by '+' (i.e. grpc, rest, custom.[something], etc?)
         'transport',
+        'warehouse-package-name'  # change the package name on PyPI
     ))
 
     @classmethod
@@ -129,6 +131,8 @@ def tweak_path(p):
         answer = Options(
             name=opts.pop('name', ['']).pop(),
             namespace=tuple(opts.pop('namespace', [])),
+            warehouse_package_name=opts.pop(
+                'warehouse-package-name', ['']).pop(),
             retry=retry_cfg,
             sample_configs=tuple(
                 cfg_path
diff --git a/tests/unit/generator/test_options.py b/tests/unit/generator/test_options.py
index 5235c2e453..60d365a84c 100644
--- a/tests/unit/generator/test_options.py
+++ b/tests/unit/generator/test_options.py
@@ -152,3 +152,8 @@ def test_options_old_naming():
 def test_options_add_iam_methods():
     opts = Options.build('add-iam-methods')
     assert opts.add_iam_methods
+
+
+def test_options_warehouse_package_name():
+    opts = Options.build('warehouse-package-name')
+    assert opts.warehouse_package_name
diff --git a/tests/unit/schema/test_naming.py b/tests/unit/schema/test_naming.py
index ec1e0dad64..c0487b7d26 100644
--- a/tests/unit/schema/test_naming.py
+++ b/tests/unit/schema/test_naming.py
@@ -218,6 +218,16 @@ def test_cli_override_name_and_namespace_versionless():
     assert not n.version
 
 
+def test_cli_override_warehouse_package_name():
+    FileDesc = descriptor_pb2.FileDescriptorProto
+    proto1 = FileDesc(package='google.translation')
+    n = naming.Naming.build(
+        proto1,
+        opts=Options(warehouse_package_name='google-cloud-foo'),
+    )
+    assert n.warehouse_package_name == "google-cloud-foo"
+
+
 def test_build_factory():
     proto = descriptor_pb2.FileDescriptorProto(
         package='google.mollusc.v1alpha1'

From f64676780d9516aa5a329999bad638002af0e340 Mon Sep 17 00:00:00 2001
From: "release-please[bot]"
 <55107282+release-please[bot]@users.noreply.github.com>
Date: Tue, 22 Dec 2020 18:14:03 +0000
Subject: [PATCH 3/3] chore: release 0.39.0 (#719)

:robot: I have created a release \*beep\* \*boop\*
---
## [0.39.0](https://www.github.com/googleapis/gapic-generator-python/compare/v0.38.0...v0.39.0) (2020-12-22)


### Features

* allow warehouse name to be customized ([#717](https://www.github.com/googleapis/gapic-generator-python/issues/717)) ([7c185e8](https://www.github.com/googleapis/gapic-generator-python/commit/7c185e87cb4252b1f99ed121515814595f9492c4)), closes [#605](https://www.github.com/googleapis/gapic-generator-python/issues/605)


### Bug Fixes

* fix sphinx identifiers ([#714](https://www.github.com/googleapis/gapic-generator-python/issues/714)) ([39be474](https://www.github.com/googleapis/gapic-generator-python/commit/39be474b4419dfa521ef51927fd36dbf257d68e3)), closes [#625](https://www.github.com/googleapis/gapic-generator-python/issues/625) [#604](https://www.github.com/googleapis/gapic-generator-python/issues/604)
---


This PR was generated with [Release Please](https://github.com/googleapis/release-please).
---
 CHANGELOG.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0c28ecdb73..3957097179 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.39.0](https://www.github.com/googleapis/gapic-generator-python/compare/v0.38.0...v0.39.0) (2020-12-22)
+
+
+### Features
+
+* allow warehouse name to be customized ([#717](https://www.github.com/googleapis/gapic-generator-python/issues/717)) ([7c185e8](https://www.github.com/googleapis/gapic-generator-python/commit/7c185e87cb4252b1f99ed121515814595f9492c4)), closes [#605](https://www.github.com/googleapis/gapic-generator-python/issues/605)
+
+
+### Bug Fixes
+
+* fix sphinx identifiers ([#714](https://www.github.com/googleapis/gapic-generator-python/issues/714)) ([39be474](https://www.github.com/googleapis/gapic-generator-python/commit/39be474b4419dfa521ef51927fd36dbf257d68e3)), closes [#625](https://www.github.com/googleapis/gapic-generator-python/issues/625) [#604](https://www.github.com/googleapis/gapic-generator-python/issues/604)
+
 ## [0.38.0](https://www.github.com/googleapis/gapic-generator-python/compare/v0.37.1...v0.38.0) (2020-12-16)