From 6ef6c5111c9b1d82209379967a056bff14f46478 Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot <44816363+yoshi-automation@users.noreply.github.com> Date: Wed, 1 May 2019 15:21:17 -0700 Subject: [PATCH] Add nox session `docs`, reorder methods (via synth). (#7775) --- kms/docs/README.rst | 1 + kms/docs/conf.py | 42 +++++++++++++++++-- kms/docs/index.rst | 2 +- .../gapic/key_management_service_client.py | 36 ++++++++-------- kms/noxfile.py | 20 +++++++++ kms/synth.metadata | 12 +++--- 6 files changed, 84 insertions(+), 29 deletions(-) create mode 120000 kms/docs/README.rst diff --git a/kms/docs/README.rst b/kms/docs/README.rst new file mode 120000 index 000000000000..89a0106941ff --- /dev/null +++ b/kms/docs/README.rst @@ -0,0 +1 @@ +../README.rst \ No newline at end of file diff --git a/kms/docs/conf.py b/kms/docs/conf.py index 8092ed683f14..2fcee231a25a 100644 --- a/kms/docs/conf.py +++ b/kms/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-kms-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 diff --git a/kms/docs/index.rst b/kms/docs/index.rst index cc9201cb05fe..7ae49b7a9bb3 100644 --- a/kms/docs/index.rst +++ b/kms/docs/index.rst @@ -1,4 +1,4 @@ -.. include:: /../kms/README.rst +.. include:: README.rst API Reference diff --git a/kms/google/cloud/kms_v1/gapic/key_management_service_client.py b/kms/google/cloud/kms_v1/gapic/key_management_service_client.py index 705c2eec6b56..2aa9dbf70b99 100644 --- a/kms/google/cloud/kms_v1/gapic/key_management_service_client.py +++ b/kms/google/cloud/kms_v1/gapic/key_management_service_client.py @@ -85,13 +85,14 @@ def from_service_account_file(cls, filename, *args, **kwargs): from_service_account_json = from_service_account_file @classmethod - def key_ring_path(cls, project, location, key_ring): - """Return a fully-qualified key_ring string.""" + def crypto_key_path(cls, project, location, key_ring, crypto_key): + """Return a fully-qualified crypto_key string.""" return google.api_core.path_template.expand( - "projects/{project}/locations/{location}/keyRings/{key_ring}", + "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}", project=project, location=location, key_ring=key_ring, + crypto_key=crypto_key, ) @classmethod @@ -106,37 +107,36 @@ def crypto_key_path_path(cls, project, location, key_ring, crypto_key_path): ) @classmethod - def location_path(cls, project, location): - """Return a fully-qualified location string.""" + def crypto_key_version_path( + cls, project, location, key_ring, crypto_key, crypto_key_version + ): + """Return a fully-qualified crypto_key_version string.""" return google.api_core.path_template.expand( - "projects/{project}/locations/{location}", + "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}", project=project, location=location, + key_ring=key_ring, + crypto_key=crypto_key, + crypto_key_version=crypto_key_version, ) @classmethod - def crypto_key_path(cls, project, location, key_ring, crypto_key): - """Return a fully-qualified crypto_key string.""" + def key_ring_path(cls, project, location, key_ring): + """Return a fully-qualified key_ring string.""" return google.api_core.path_template.expand( - "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}", + "projects/{project}/locations/{location}/keyRings/{key_ring}", project=project, location=location, key_ring=key_ring, - crypto_key=crypto_key, ) @classmethod - def crypto_key_version_path( - cls, project, location, key_ring, crypto_key, crypto_key_version - ): - """Return a fully-qualified crypto_key_version string.""" + def location_path(cls, project, location): + """Return a fully-qualified location string.""" return google.api_core.path_template.expand( - "projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}", + "projects/{project}/locations/{location}", project=project, location=location, - key_ring=key_ring, - crypto_key=crypto_key, - crypto_key_version=crypto_key_version, ) def __init__( diff --git a/kms/noxfile.py b/kms/noxfile.py index d692cf37f39c..0f528b7f3902 100644 --- a/kms/noxfile.py +++ b/kms/noxfile.py @@ -16,6 +16,7 @@ from __future__ import absolute_import import os +import shutil import nox @@ -138,3 +139,22 @@ def cover(session): session.run("coverage", "report", "--show-missing", "--fail-under=100") session.run("coverage", "erase") + +@nox.session(python="3.7") +def docs(session): + """Build the docs for this library.""" + + session.install('-e', '.') + session.install('sphinx', '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', ''), + ) diff --git a/kms/synth.metadata b/kms/synth.metadata index 8ae21bcb7d2c..72827ab9263d 100644 --- a/kms/synth.metadata +++ b/kms/synth.metadata @@ -1,26 +1,26 @@ { - "updateTime": "2019-04-16T12:18:58.998401Z", + "updateTime": "2019-05-01T20:25:40.444411Z", "sources": [ { "generator": { "name": "artman", - "version": "0.16.25", - "dockerImage": "googleapis/artman@sha256:d9597f983d1d4e61272c63cb97b7d8f8234da9999526c35d357de3d781f0ec1b" + "version": "0.17.1", + "dockerImage": "googleapis/artman@sha256:a40ca4dd4ef031c0ded4df4909ffdf7b3f20d29b23e682ef991eb60ba0ca6025" } }, { "git": { "name": "googleapis", "remote": "https://github.com/googleapis/googleapis.git", - "sha": "b7f88d8827df8a78e1bb1d56b0f56a1bc23c6359", - "internalRef": "243675277" + "sha": "316b54c401ab9bc08ed71cb362915b9e7a23bb05", + "internalRef": "246014263" } }, { "template": { "name": "python_library", "origin": "synthtool.gcp", - "version": "2019.4.10" + "version": "2019.4.24" } } ],