Merge branch 'retrieve_args' of github.com:googleapis/sphinx-docfx-ya…

…ml into retrieve_args

.kokoro/generate-docs.sh

@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Update 2024-08-12: We are using python3.10 explicitly everywhere to
+# avoid `test(3.10)` failures.
+
 # Should run regardless of failure status for the generator.
 set +eo pipefail
 
@@ -30,8 +33,8 @@ gcloud auth activate-service-account --key-file ${GOOGLE_APPLICATION_CREDENTIALS
 
 # Install dependencies.
 # Disable dependency resolver as all dependencies should have been laid out.
-python3 -m pip install --no-deps --require-hashes -r .kokoro/requirements.txt
-python3 -m pip install -e .
+python3.10 -m pip install --no-deps --require-hashes -r .kokoro/requirements.txt
+python3.10 -m pip install -e .
 
 # Store the contents of bucket log in a variable to reuse.
 python_bucket_items=$(gsutil ls "gs://docs-staging-v2/docfx-python*")
@@ -100,24 +103,24 @@ for package in $(echo "${python_bucket_items}" | cut -d "-" -f 5- | rev | cut -d
     ## Build HTML docs for googleapis.dev.
     # nox -s docs
 
-    # python3 -m docuploader create-metadata \
+    # python3.10 -m docuploader create-metadata \
     #  --name=$(jq --raw-output '.name // empty' .repo-metadata.json) \
-    #  --version=$(python3 setup.py --version) \
+    #  --version=$(python3.10 setup.py --version) \
     #  --language=$(jq --raw-output '.language // empty' .repo-metadata.json) \
-    #  --distribution-name=$(python3 setup.py --name) \
+    #  --distribution-name=$(python3.10 setup.py --name) \
     #  --product-page=$(jq --raw-output '.product_documentation // empty' .repo-metadata.json) \
     #  --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \
     #  --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json)
 
     # cat docs.metadata
 
     ## upload docs
-    # python3 -m docuploader upload docs/_build/html --metadata-file docs.metadata --staging-bucket "${STAGING_BUCKET}"
+    # python3.10 -m docuploader upload docs/_build/html --metadata-file docs.metadata --staging-bucket "${STAGING_BUCKET}"
 
     # Test running with the plugin version locally.
     if [[ "${TEST_PLUGIN}" == "true" ]]; then
       # --no-use-pep517 is required for django-spanner install issue: see https://github.com/pypa/pip/issues/7953
-      python3 -m pip install --user --no-use-pep517 -e .[all]
+      python3.10 -m pip install --user --no-use-pep517 -e .[all]
       sphinx-build -T -N -D extensions=sphinx.ext.autodoc,sphinx.ext.autosummary,docfx_yaml.extension,sphinx.ext.intersphinx,sphinx.ext.coverage,sphinx.ext.napoleon,sphinx.ext.todo,sphinx.ext.viewcode,recommonmark -b html -d docs/_build/doctrees/ docs/ docs/_build/html/
       continue
     fi
@@ -143,19 +146,19 @@ for package in $(echo "${python_bucket_items}" | cut -d "-" -f 5- | rev | cut -d
       name="iam"
     fi
 
-    python3 -m docuploader create-metadata \
+    python3.10 -m docuploader create-metadata \
       --name=${name} \
-      --version=$(python3 setup.py --version) \
+      --version=$(python3.10 setup.py --version) \
       --language=$(jq --raw-output '.language // empty' .repo-metadata.json) \
-      --distribution-name=$(python3 setup.py --name) \
+      --distribution-name=$(python3.10 setup.py --name) \
       --product-page=$(jq --raw-output '.product_documentation // empty' .repo-metadata.json) \
       --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \
       --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json)
 
     cat docs.metadata
 
     # upload docs
-    python3 -m docuploader upload docs/_build/html/docfx_yaml --metadata-file docs.metadata --destination-prefix docfx --staging-bucket "${V2_STAGING_BUCKET}"
+    python3.10 -m docuploader upload docs/_build/html/docfx_yaml --metadata-file docs.metadata --destination-prefix docfx --staging-bucket "${V2_STAGING_BUCKET}"
   done
 
   # Clean up the repository to make room.
@@ -178,7 +181,7 @@ if [ -n "${monorepo_packages}" ]; then
     # Test running with the plugin version locally.
     if [[ "${TEST_PLUGIN}" == "true" ]]; then
       # --no-use-pep517 is required for django-spanner install issue: see https://github.com/pypa/pip/issues/7953
-      python3 -m pip install --user --no-use-pep517 -e .[all]
+      python3.10 -m pip install --user --no-use-pep517 -e .[all]
       sphinx-build -T -N -D extensions=sphinx.ext.autodoc,sphinx.ext.autosummary,docfx_yaml.extension,sphinx.ext.intersphinx,sphinx.ext.coverage,sphinx.ext.napoleon,sphinx.ext.todo,sphinx.ext.viewcode,recommonmark -b html -d docs/_build/doctrees/ docs/ docs/_build/html/
       continue
     fi
@@ -192,19 +195,19 @@ if [ -n "${monorepo_packages}" ]; then
       continue
     fi
 
-    python3 -m docuploader create-metadata \
+    python3.10 -m docuploader create-metadata \
       --name=$(jq --raw-output '.name // empty' .repo-metadata.json) \
-      --version=$(python3 setup.py --version) \
+      --version=$(python3.10 setup.py --version) \
       --language=$(jq --raw-output '.language // empty' .repo-metadata.json) \
-      --distribution-name=$(python3 setup.py --name) \
+      --distribution-name=$(python3.10 setup.py --name) \
       --product-page=$(jq --raw-output '.product_documentation // empty' .repo-metadata.json) \
       --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \
       --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json)
 
     cat docs.metadata
 
     # upload docs
-    python3 -m docuploader upload docs/_build/html/docfx_yaml --metadata-file docs.metadata --destination-prefix docfx --staging-bucket "${V2_STAGING_BUCKET}"
+    python3.10 -m docuploader upload docs/_build/html/docfx_yaml --metadata-file docs.metadata --destination-prefix docfx --staging-bucket "${V2_STAGING_BUCKET}"
 
     # Clean up the package to make room.
     cd ../

.kokoro/requirements.txt

@@ -38,9 +38,9 @@ cachetools==5.2.0 \
     --hash=sha256:6a94c6402995a99c3970cc7e4884bb60b4a8639938157eeed436098bf9831757 \
     --hash=sha256:f9f17d2aec496a9aa6b76f53e3b614c965223c061982d434d160f930c698a9db
     # via google-auth
-certifi==2023.7.22 \
-    --hash=sha256:539cc1d13202e33ca466e88b2807e29f4c13049d6d87031a3c110744495cb082 \
-    --hash=sha256:92d6037539857d8206b8f6ae472e8b77db8058fec5937a1ef3f54304089edbb9
+certifi==2024.7.4 \
+    --hash=sha256:5a1e7645bc0ec61a09e26c36f6106dd4cf40c6db3a1fb6352b0244e7fb057c7b \
+    --hash=sha256:c198e21b1289c2ab85ee4e67bb4b4ef3ead0892059901a8d5b622f24a1101e90
     # via requests
 cffi==1.15.1 \
     --hash=sha256:00a9ed42e88df81ffae7a8ab6d9356b371399b91dbdf0c3cb1e84c03a13aceb5 \
@@ -956,13 +956,13 @@ wheel==0.38.4 \
     --hash=sha256:965f5259b566725405b05e7cf774052044b1ed30119b5d586b2703aafe8719ac \
     --hash=sha256:b60533f3f5d530e971d6737ca6d58681ee434818fab630c83a734bb10c083ce8
     # via -r requirements.in
-zipp==3.8.1 \
-    --hash=sha256:05b45f1ee8f807d0cc928485ca40a07cb491cf092ff587c0df9cb1fd154848d2 \
-    --hash=sha256:47c40d7fe183a6f21403a199b3e4192cca5774656965b0a4988ad2f8feb5f009
+zipp==3.19.1 \
+    --hash=sha256:2828e64edb5386ea6a52e7ba7cdb17bb30a73a858f5eb6eb93d8d36f5ea26091 \
+    --hash=sha256:35427f6d5594f4acf82d25541438348c26736fa9b3afa2754bcd63cdb99d8e8f
     # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
-setuptools==68.2.2 \
-    --hash=sha256:4ac1475276d2f1c48684874089fefcd83bd7162ddaafb81fac866ba0db282a87 \
-    --hash=sha256:b454a35605876da60632df1a60f736524eb73cc47bbc9f3f1ef1b644de74fd2a
+setuptools==70.0.0 \
+    --hash=sha256:54faa7f2e8d2d11bcd2c07bed282eef1046b5c080d1c32add737d7b5817b1ad4 \
+    --hash=sha256:f211a66637b8fa059bb28183da127d4e86396c991a942b028c6650d4319c3fd0
     # via -r requirements.in

docfx_yaml/extension.py

@@ -162,6 +162,10 @@ class Bcolors:
 logging.getLogger("blib2to3").setLevel(logging.ERROR)
 
 
+# Type alias used for yaml entries.
+_yaml_type_alias = dict[str, any]
+
+
 def _grab_repo_metadata() -> Mapping[str, str] | None:
     """Retrieves the repository's metadata info if found."""
     try:
@@ -1427,10 +1431,18 @@ def find_unique_name(package_name, entries):
     # If there is no way to disambiguate or we found duplicates, return the identifier name.
     return [package_name[-1]]
 
-# Used to disambiguate names that have same entries.
-# Returns a dictionary of names that are disambiguated in the form of:
-# {uidname: disambiguated_name}
-def disambiguate_toc_name(pkg_toc_yaml):
+
+def disambiguate_toc_name(
+    pkg_toc_yaml: _yaml_type_alias,
+) -> Mapping[str, str]:
+    """Disambiguates names that have same entries in table of contents.
+
+    Args:
+        pkg_toc_yaml: The table of contents for the client library.
+
+    Returns:
+        Mapping from uidname to disambiguated name.
+    """
     name_entries = {}
     disambiguated_names = {}
 
@@ -1439,13 +1451,21 @@ def disambiguate_toc_name(pkg_toc_yaml):
         if module_name not in name_entries:
             name_entries[module_name] = {}
 
+        prev_part = ""
         # Split the name and mark all duplicates.
         # There will be at least 1 unique identifer for each name.
         for part in module['uidname'].split("."):
-            if part not in name_entries[module_name]:
+            if part not in name_entries[module_name] or (
+                # If the name appears in a row, for example:
+                #   google.cloud.run_v2.services
+                #   google.cloud.run_v2.services.services
+                # then ignore this entry as this is clear from the left-nav layout.
+                part == prev_part
+            ):
                 name_entries[module_name][part] = 1
             else:
                 name_entries[module_name][part] += 1
+            prev_part = part
 
         # Some entries don't contain `name` in `uidname`, add these into the map as well.
         if module_name not in name_entries[module_name]:
@@ -1457,7 +1477,7 @@ def disambiguate_toc_name(pkg_toc_yaml):
 
     for module in pkg_toc_yaml:
         module_name = module['name']
-        # Check if there are multiple entires of module['name'], disambiguate if needed.
+        # Check if there are multiple entries of module['name'], disambiguate if needed.
         if name_entries[module_name][module_name] > 1:
             module['name'] = ".".join(find_unique_name(module['uidname'].split("."), name_entries[module_name]))
             disambiguated_names[module['uidname']] = module['name']
@@ -1502,10 +1522,6 @@ def pretty_package_name(package_group):
     return " ".join(capitalized_name)
 
 
-# Type alias used for yaml entries.
-_yaml_type_alias = dict[str, any]
-
-
 def _find_and_add_summary_details(
     yaml_data: _yaml_type_alias,
     summary_type: str,

tests/test_unit.py

@@ -53,7 +53,13 @@ def test_finds_unique_name(self):
                 "google.api_core.client_info": "client_info",
                 "google.api_core.gapic_v1.client_info": "gapic_v1.client_info",
             },
-        ]
+        ],
+        [
+            # Tests repeated duplicates in a row. No changes expected.
+            "tests/yaml_repeat_duplicate.yaml",
+            "tests/yaml_repeat_duplicate.yaml",
+            {},
+        ],
     ]
     @parameterized.expand(test_entries)
     def test_disambiguates_toc_name(

tests/yaml_repeat_duplicate.yaml

@@ -0,0 +1,18 @@
+[
+   {
+      "name":"Services",
+      "uidname":"google.cloud.run_v2.services",
+      "items":[
+         {
+            "name":"Overview",
+            "uidname":"google.cloud.run_v2.services.services",
+            "uid":"google.cloud.run_v2.services.services",
+         },
+         {
+            "name":"Pagers",
+            "uidname":"google.cloud.run_v2.pagers",
+            "uid":"google.cloud.run_v2.pagers",
+         }
+      ]
+   },
+]

tox.ini

@@ -1,5 +1,7 @@
 [tox]
-envlist = tests
+envlist =
+    tests
+    py310
 
 [testenv]
 setenv =