Strict sphinx (Azure#32507)

* Add strict_sphinx mode

* Doc

* cspell

Author: lmazuel

doc/eng_sys_checks.md

@@ -118,6 +118,8 @@ Starting with [this pr](https://github.com/Azure/azure-sdk-for-python/pull/28345
 
 We default to **enabling** most of our checks like `pylint`, `mypy`, etc. Due to that, most `pyproject.toml` settings will likely be **disabling** checks.
 
+There is also an additional setting to turn on strict sphinx validation, for docstring validation.
+
 Here's an example:
 
 ```toml
@@ -130,6 +132,7 @@ verifytypes = false
 pyright = false
 pylint = false
 black = false
+strict_sphinx = false
 ```
 
 If a package does not yet have a `pyproject.toml`, creating one with just the section `[tool.azure-sdk-build]` will do no harm to the release of the package in question.
@@ -195,9 +198,20 @@ Analyze job in both nightly CI and pull request validation pipeline runs a set o
 
 1. Go to root of the package.
 2. Execute following command: `tox run -e pylint -c ../../../eng/tox/tox.ini --root .`
-  
+
 Note that the `pylint` environment is configured to run against the **earliest supported python version**. This means that users **must** have `python 3.7` installed on their machine to run this check locally.
 
+### Sphinx and docstring checker
+
+[`Sphinx`](https://www.sphinx-doc.org/en/master/) is the preferred documentation builder for Python libraries. The documentation is always built and attached to each PR builds. Sphinx can be configured to
+fail if docstring are invalid, helping to ensure the resulting documentation will be of high quality. Following are the steps to run `sphinx` locally for a specific package with strict docstring checking:
+
+1. Go to root of the package.
+2. Make sure the `pyproject.toml` file contains `strict_sphinx = true`
+3. Execute following command: `tox run -e sphinx -c ../../../eng/tox/tox.ini --root .`
+
+Note: While as of now the default value is `False`, it will become `True` by mid 2024.
+
 ### Bandit
 
 `Bandit` is static security analysis tool. This check is triggered for all Azure SDK package as part of analyze job. Following are the steps to `Bandit` tool locally for a specific package.

eng/tox/run_sphinx_build.py

@@ -22,6 +22,7 @@
 import shutil
 
 from ci_tools.parsing import ParsedSetup
+from ci_tools.functions import get_config_setting
 
 logging.getLogger().setLevel(logging.INFO)
 
@@ -39,7 +40,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):
+def sphinx_build(target_dir, output_dir, fail_on_warning=False):
     command_array = [
                 "sphinx-build",
                 "-b",
@@ -51,6 +52,9 @@ def sphinx_build(target_dir, output_dir):
                 target_dir,
                 output_dir
             ]
+    if fail_on_warning:
+        command_array.append("-W")
+        command_array.append("--keep-going")
 
     try:
         logging.info("Sphinx build command: {}".format(command_array))
@@ -59,7 +63,7 @@ def sphinx_build(target_dir, output_dir):
         )
     except CalledProcessError as e:
         logging.error(
-            "sphinx-apidoc failed for path {} exited with error {}".format(
+            "sphinx-build failed for path {} exited with error {}".format(
                 args.working_directory, e.returncode
             )
         )
@@ -103,15 +107,16 @@ def sphinx_build(target_dir, output_dir):
 
     args = parser.parse_args()
 
-    
     output_dir = os.path.abspath(args.output_directory)
     target_dir = os.path.abspath(args.working_directory)
     package_dir = os.path.abspath(args.package_root)
 
     pkg_details = ParsedSetup.from_path(package_dir)
 
     if should_build_docs(pkg_details.name):
-        sphinx_build(target_dir, output_dir)
+        fail_on_warning = get_config_setting(args.package_root, "strict_sphinx", default=False)
+
+        sphinx_build(target_dir, output_dir, fail_on_warning=fail_on_warning)
 
         if in_ci() or args.in_ci:
             move_output_and_compress(output_dir, package_dir, pkg_details.name)