chore(python): autogenerate docs/index.rst

synthtool/gcp/common.py

@@ -209,7 +209,15 @@ def py_library(self, **kwargs) -> Path:
         # kwargs["metadata"] is required to load values from .repo-metadata.json
         if "metadata" not in kwargs:
             kwargs["metadata"] = {}
-        # rename variable to accomodate existing synth.py files
+
+        # load common repo meta information (metadata that's not language specific).
+        self._load_generic_metadata(kwargs["metadata"])
+
+        # initialize default_version if it doesn't exist in kwargs["metadata"]['repo']
+        if "default_version" not in kwargs["metadata"]["repo"]:
+            kwargs["metadata"]["repo"]["default_version"] = ""
+
+        # rename variable to accommodate existing owlbot.py files
         if "system_test_dependencies" in kwargs:
             kwargs["system_test_local_dependencies"] = kwargs[
                 "system_test_dependencies"
@@ -237,6 +245,13 @@ def py_library(self, **kwargs) -> Path:
         if "samples" not in kwargs:
             self.excludes += ["samples/AUTHORING_GUIDE.md", "samples/CONTRIBUTING.md"]
 
+        # Don't add `docs/index.rst` if `versions` is not provided or `default_version` is empty
+        if (
+            "versions" not in kwargs
+            or not kwargs["metadata"]["repo"]["default_version"]
+        ):
+            self.excludes += ["docs/index.rst"]
+
         # Assume the python-docs-samples Dockerfile is used for samples by default
         if "custom_samples_dockerfile" not in kwargs:
             kwargs["custom_samples_dockerfile"] = False

synthtool/gcp/templates/python_library/docs/index.rst

@@ -0,0 +1,36 @@
+.. include:: README.rst
+
+.. include:: multiprocessing.rst
+{% if versions|length > 1 %}
+This package includes clients for multiple versions of {{ metadata['repo']['name_pretty'] }}.
+By default, you will get version ``{{ versions | first }}``.
+{% endif %}
+{% for version in versions %}
+API Reference
+-------------
+.. toctree::
+    :maxdepth: 2
+
+    {{ version }}/services
+    {{ version }}/types
+{% endfor %}
+{%- if migration_guide_version %}
+Migration Guide
+---------------
+
+See the guide below for instructions on migrating to the {{ migration_guide_version }} release of this library.
+
+.. toctree::
+    :maxdepth: 2
+
+    UPGRADING
+{% endif %}
+Changelog
+---------
+
+For a list of all ``{{ metadata['repo']['distribution_name'] }}`` releases:
+
+.. toctree::
+   :maxdepth: 2
+
+   changelog

synthtool/languages/python.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import json
 import re
 import sys
 from pathlib import Path
@@ -93,6 +94,50 @@ def _get_sample_readme_metadata(sample_dir: Path) -> dict:
     return sample_metadata
 
 
+def detect_versions(path: str = "./google/cloud") -> List[str]:
+    """
+    Detects the versions a library has, based on distinct folders
+    within path. This is based on the fact that our GAPIC libraries are
+    structured as follows:
+
+    google/cloud/*_v1
+    google/cloud/*_v1beta
+    google/cloud/*_v1alpha
+
+    With folder names mapping directly to versions.
+
+    Returns: a list of the subdirectories; for the example above:
+      ['*_v1', '*_v1alpha', '*_v1beta']
+      The subdirectory with the same suffix as the default_version
+      specified in .repo-metadata.json will be first in the list. The
+      remaining elements will be sorted alphabetically.
+    """
+
+    versions = []
+
+    # Get the default_version from .repo-metadata.json
+    default_version = json.load(open(".repo-metadata.json", "rt")).get(
+        "default_version"
+    )
+
+    # Sort the sub directories alphabetically
+    sub_dirs = sorted([p.name for p in Path(path).glob("**/*_v[1-9]*")])
+
+    if default_version and sub_dirs:
+        # The subdirectory with the same suffix as the default_version
+        # specified in .repo-metadata.json will be the default client.
+        default_client = next(
+            iter([d for d in sub_dirs if d.endswith(default_version)]), None
+        )
+        if default_client:
+            # The default_client will be first in the list.
+            # The remaining elements will be sorted alphabetically.
+            versions = [default_client] + [
+                d for d in sub_dirs if not d.endswith(default_version)
+            ]
+    return versions
+
+
 def py_samples(*, root: PathOrStr = None, skip_readmes: bool = False) -> None:
     """
     Find all samples projects and render templates.

tests/test_python_library.py

@@ -12,13 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import json
 import os
 from pathlib import Path
 
 import pytest
+import tempfile
 
 from synthtool import gcp
 from synthtool.sources import templates
+from synthtool.languages import python
 from . import util
 
 
@@ -126,3 +129,77 @@ def test_split_system_tests():
         with open(templated_files / ".kokoro/presubmit/system-3.8.cfg", "r") as f:
             contents = f.read()
             assert "system-3.8" in contents
+
+
+def test_detect_versions_non_default_path():
+    temp_dir = Path(tempfile.mkdtemp())
+    src_dir = temp_dir / "src"
+    for v in ("api_v1", "api_v2", "api_v3"):
+        os.makedirs(src_dir / v)
+
+    with util.chdir(temp_dir):
+        # Set default_version to "api_v1"
+        test_json = {"default_version": "api_v1"}
+        with open(".repo-metadata.json", "w") as metadata:
+            json.dump(test_json, metadata)
+
+        versions = python.detect_versions(src_dir)
+        assert ["api_v1", "api_v2", "api_v3"] == versions
+
+
+def test_detect_versions_default_path():
+    temp_dir = Path(tempfile.mkdtemp())
+    default_dir = temp_dir / "google/cloud"
+    for v in ("api_v1", "api_v2", "api_v3"):
+        os.makedirs(default_dir / v)
+
+    with util.chdir(temp_dir):
+        # Set default_version to "api_v1"
+        test_json = {"default_version": "api_v1"}
+
+        with open(".repo-metadata.json", "w") as metadata:
+            json.dump(test_json, metadata)
+
+        versions = python.detect_versions()
+        assert ["api_v1", "api_v2", "api_v3"] == versions
+
+
+def test_detect_versions_dir_not_found():
+    temp_dir = Path(tempfile.mkdtemp())
+
+    with util.chdir(temp_dir):
+        # Set default_version to "api_v1"
+        test_json = {"default_version": "api_v1"}
+        with open(".repo-metadata.json", "w") as metadata:
+            json.dump(test_json, metadata)
+        versions = python.detect_versions(temp_dir / "does-not-exist")
+        assert [] == versions
+
+
+def test_detect_versions_with_default_version():
+    temp_dir = Path(tempfile.mkdtemp())
+    default_dir = temp_dir / "google/cloud"
+    for v in ("api_v1", "api_v2", "api_v3"):
+        os.makedirs(default_dir / v)
+
+    with util.chdir(temp_dir):
+        # Set default_version to "api_v1"
+        test_json = {"default_version": "api_v1"}
+        with open(".repo-metadata.json", "w") as metadata:
+            json.dump(test_json, metadata)
+        versions = python.detect_versions()
+        assert ["api_v1", "api_v2", "api_v3"] == versions
+
+        # Set default_version to "api_v2"
+        test_json = {"default_version": "api_v2"}
+        with open(".repo-metadata.json", "w") as metadata:
+            json.dump(test_json, metadata)
+        versions = python.detect_versions()
+        assert ["api_v2", "api_v1", "api_v3"] == versions
+
+        # Set default_version to "api_v3"
+        test_json = {"default_version": "api_v3"}
+        with open(".repo-metadata.json", "w") as metadata:
+            json.dump(test_json, metadata)
+        versions = python.detect_versions()
+        assert ["api_v3", "api_v1", "api_v2"] == versions