create GH issues for strict sphinx (#33404)

* add strict-sphinx for issue creation

* add vnext_issue creator to run_sphinx_build

* add GH_TOKEN to generate docs to step

* update template

* update date to april deadline

* don't need args

* only open issues if running in analyze-weekly

* add in rohit's feedback

Author: kristapratico

eng/pipelines/templates/stages/python-analyze-weekly.yml

@@ -96,3 +96,5 @@ stages:
                 ${{ parameters.BuildTargetingString }}
                 --service="${{ parameters.ServiceDirectory }}" 
                 --toxenv="strict-sphinx"
+            env:
+              GH_TOKEN: $(azuresdk-github-pat)

eng/tox/run_sphinx_build.py

@@ -23,6 +23,7 @@
 
 from ci_tools.parsing import ParsedSetup
 from ci_tools.functions import get_config_setting
+from gh_tools.vnext_issue_creator import create_vnext_issue
 
 logging.getLogger().setLevel(logging.INFO)
 
@@ -40,7 +41,7 @@ def move_output_and_compress(target_dir, package_dir, package_name):
     individual_zip_location = os.path.join(ci_doc_dir, package_name, package_name)
     shutil.make_archive(individual_zip_location, 'gztar', target_dir)
 
-def sphinx_build(target_dir, output_dir, fail_on_warning=False):
+def sphinx_build(target_dir, output_dir, fail_on_warning=False, package_name=None):
     command_array = [
                 "sphinx-build",
                 "-b",
@@ -67,6 +68,8 @@ def sphinx_build(target_dir, output_dir, fail_on_warning=False):
                 args.working_directory, e.returncode
             )
         )
+        if args.strict and in_ci():
+            create_vnext_issue(package_name, "sphinx")
         exit(1)
 
 if __name__ == "__main__":
@@ -122,7 +125,12 @@ def sphinx_build(target_dir, output_dir, fail_on_warning=False):
     if should_build_docs(pkg_details.name):
         fail_on_warning = args.strict or get_config_setting(args.package_root, "strict_sphinx", default=False)
 
-        sphinx_build(target_dir, output_dir, fail_on_warning=fail_on_warning)
+        sphinx_build(
+            target_dir,
+            output_dir,
+            fail_on_warning=fail_on_warning,
+            package_name=pkg_details.name
+        )
 
         if in_ci() or args.in_ci:
             move_output_and_compress(output_dir, package_dir, pkg_details.name)

tools/azure-sdk-tools/gh_tools/vnext_issue_creator.py

@@ -18,8 +18,10 @@
 
 logging.getLogger().setLevel(logging.INFO)
 
+CHECK_TYPE = Literal["mypy", "pylint", "pyright", "sphinx"]
 
-def get_version_running(check_type: Literal["mypy", "pylint", "pyright"]) -> str:
+
+def get_version_running(check_type: CHECK_TYPE) -> str:
     commands = [
         sys.executable,
         "-m",
@@ -37,7 +39,7 @@ def get_version_running(check_type: Literal["mypy", "pylint", "pyright"]) -> str
     return version_running
 
 
-def get_build_link(check_type: Literal["mypy", "pylint", "pyright"]) -> str:
+def get_build_link(check_type: CHECK_TYPE) -> str:
     build_id = os.getenv('BUILD_BUILDID')
     job_id = os.getenv('SYSTEM_JOBID')
 
@@ -48,6 +50,8 @@ def get_build_link(check_type: Literal["mypy", "pylint", "pyright"]) -> str:
         next_id = "c0edaab3-85d6-5e4b-81a8-d1190a6ee92b"
     if check_type == "pylint":
         next_id = "e1fa7d9e-8471-5a74-cd7d-e1c9a992e07e"
+    if check_type == "sphinx":
+        next_id = "0d206e13-b346-5d3f-79e6-d5bfba9e089e"
 
     return f"https://dev.azure.com/azure-sdk/internal/_build/results?buildId={build_id}&view=logs&j={job_id}&t={next_id}"    
 
@@ -85,7 +89,7 @@ def get_date_for_version_bump(today: datetime.datetime) -> str:
     return merge_date.strftime('%Y-%m-%d')
 
 
-def create_vnext_issue(package_name: str, check_type: Literal["mypy", "pylint", "pyright"]) -> None:
+def create_vnext_issue(package_name: str, check_type: CHECK_TYPE) -> None:
     """This is called when a client library fails a vnext check.
     An issue is created with the details or an existing issue is updated with the latest information."""
 
@@ -100,24 +104,43 @@ def create_vnext_issue(package_name: str, check_type: Literal["mypy", "pylint",
 
     version = get_version_running(check_type)
     build_link = get_build_link(check_type)
-    merge_date = get_date_for_version_bump(today)
-    error_type = "linting" if check_type == "pylint" else "typing"
-    guide_link = "[Pylint Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md)" \
-        if check_type == "pylint" else "[Typing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking.md#run-mypy)"
-
-    title = f"{package_name} needs {error_type} updates for {check_type} version {version}"
-    template = (
-        f"**ACTION NEEDED:** This version of {check_type} will be merged on **{merge_date}**. "
-        f"The build will begin to fail for this library if errors are not fixed."
-        f"\n\n**Library name:** {package_name}"
-        f"\n**{check_type.capitalize()} version:** {version}"
-        f"\n**{check_type.capitalize()} errors:** [Link to build ({today.strftime('%Y-%m-%d')})]({build_link})"
-        f"\n**How to fix:** Run the `next-{check_type}` tox command at the library package-level and resolve "
-        f"the {error_type} errors.\n"
-        f"1) `../{package_name}>pip install \"tox<5\"`\n"
-        f"2) `../{package_name}>tox run -e next-{check_type} -c ../../../eng/tox/tox.ini --root .`\n\n"
-        f"See the {guide_link} for more information."
-    )
+    if check_type == "sphinx":
+        merge_date = "2024-04-15" # This is a one-time event
+        error_type = "docstring"
+        guide_link = "[Sphinx and docstring checker](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/eng_sys_checks.md#sphinx-and-docstring-checker)"
+        title = f"{package_name} needs {error_type} updates for {check_type}"
+        template = (
+            f"**ACTION NEEDED:** All {check_type} errors and warnings must be fixed by **{merge_date}**. "
+            f"The build will begin to fail for this library if errors are not fixed."
+            f"\n\nThis issue indicates that your library reference documentation is rendering with errors. To avoid customer issues, please ensure you take care of these errors and warnings ASAP."
+            f"\n\n**Library name:** {package_name}"
+            f"\n**{check_type.capitalize()} build:** [Link to build ({today.strftime('%Y-%m-%d')})]({build_link})"
+            f"\n**How to fix:** Run the `strict-{check_type}` tox command at the library package-level and resolve "
+            f"the {error_type} errors and warnings.\n"
+            f"1) `../{package_name}>pip install \"tox<5\"`\n"
+            f"2) `../{package_name}>tox run -e strict-{check_type} -c ../../../eng/tox/tox.ini --root .`\n\n"
+            f"3) Once resolved, set `strict_sphinx = true` in the package's pyproject.toml file.\n\n"
+            f"See {guide_link} for more information."
+        )
+    else:
+        merge_date = get_date_for_version_bump(today)
+        error_type = "linting" if check_type == "pylint" else "typing"
+        guide_link = "[Pylint Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md)" \
+            if check_type == "pylint" else "[Typing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking.md#run-mypy)"
+
+        title = f"{package_name} needs {error_type} updates for {check_type} version {version}"
+        template = (
+            f"**ACTION NEEDED:** This version of {check_type} will be merged on **{merge_date}**. "
+            f"The build will begin to fail for this library if errors are not fixed."
+            f"\n\n**Library name:** {package_name}"
+            f"\n**{check_type.capitalize()} version:** {version}"
+            f"\n**{check_type.capitalize()} errors:** [Link to build ({today.strftime('%Y-%m-%d')})]({build_link})"
+            f"\n**How to fix:** Run the `next-{check_type}` tox command at the library package-level and resolve "
+            f"the {error_type} errors.\n"
+            f"1) `../{package_name}>pip install \"tox<5\"`\n"
+            f"2) `../{package_name}>tox run -e next-{check_type} -c ../../../eng/tox/tox.ini --root .`\n\n"
+            f"See the {guide_link} for more information."
+        )
 
     # create an issue for the library failing the vnext check
     if not vnext_issue: