chore(python): autogenerate docs/index.rst

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

@@ -0,0 +1,38 @@
+.. include:: README.rst
+
+.. include:: multiprocessing.rst
+{% if default_version %}
+{% if versions|length > 1 %}
+This package includes clients for multiple versions of {{ metadata['repo']['name_pretty'] }}.
+By default, you will get version ``{{ default_version }}``.
+{% endif %}
+{% 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,10 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import os
 import re
 import sys
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any, Dict, List, Optional
 
 import yaml
 
@@ -93,6 +94,36 @@ def _get_sample_readme_metadata(sample_dir: Path) -> dict:
     return sample_metadata
 
 
+def detect_versions(
+    path: str = "./src", default_version: Optional[str] = None
+) -> 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:
+
+    src/v1
+    src/v1beta
+    src/v1alpha
+
+    With folder names mapping directly to versions.
+
+    Returns: a list of the subdirectories; for the example above:
+      ['v1', 'v1alpha', 'v1beta']
+      If specified, the default_version is guaranteed to be listed last.
+      Otherwise, the list is sorted alphabetically.
+    """
+    versions = []
+    if os.path.isdir(path):
+        for directory in os.listdir(path):
+            if os.path.isdir(os.path.join(path, directory)):
+                versions.append(directory)
+    versions.sort()
+    if default_version is not None:
+        versions = [v for v in versions if v != default_version] + [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

@@ -16,9 +16,11 @@
 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 +128,47 @@ 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_src():
+    temp_dir = Path(tempfile.mkdtemp())
+    src_dir = temp_dir / "src"
+    for v in ("v1", "v2", "v3"):
+        os.makedirs(src_dir / v)
+
+    with util.chdir(temp_dir):
+        versions = python.detect_versions()
+        assert ["v1", "v2", "v3"] == versions
+
+
+def test_detect_versions_staging():
+    temp_dir = Path(tempfile.mkdtemp())
+    staging_dir = temp_dir / "owl-bot-staging"
+    for v in ("v1", "v2", "v3"):
+        os.makedirs(staging_dir / v)
+
+    versions = python.detect_versions(staging_dir)
+    assert ["v1", "v2", "v3"] == versions
+
+
+def test_detect_versions_dir_not_found():
+    temp_dir = Path(tempfile.mkdtemp())
+
+    versions = python.detect_versions(temp_dir / "does-not-exist")
+    assert [] == versions
+
+
+def test_detect_versions_with_default():
+    temp_dir = Path(tempfile.mkdtemp())
+    src_dir = temp_dir / "src"
+    vs = ("v1", "v2", "v3")
+    for v in vs:
+        os.makedirs(src_dir / v)
+
+    with util.chdir(temp_dir):
+        versions = python.detect_versions(default_version="v1")
+        assert ["v2", "v3", "v1"] == versions
+        versions = python.detect_versions(default_version="v2")
+        assert ["v1", "v3", "v2"] == versions
+        versions = python.detect_versions(default_version="v3")
+        assert ["v1", "v2", "v3"] == versions