[MAINTENANCE] Lint Docs

docs/checks/docs_link_checker.py

@@ -12,10 +12,10 @@
 """
 from __future__ import annotations
 
-import glob
 import logging
-import os
+import pathlib
 import re
+import sys
 from typing import List, Optional
 
 import click
@@ -35,7 +35,7 @@ class LinkReport:
         message: A message describing the failure.
     """
 
-    def __init__(self, link: str, file: str, message: str):
+    def __init__(self, link: str, file: pathlib.Path, message: str):
         self.link = link
         self.file = file
         self.message = message
@@ -49,8 +49,8 @@ class LinkChecker:
 
     def __init__(
         self,
-        docs_path: str,
-        docs_root: str,
+        docs_path: pathlib.Path,
+        docs_root: pathlib.Path,
         site_prefix: str,
         skip_external: bool = False,
     ):
@@ -62,8 +62,8 @@ def __init__(
             site_prefix: The top-level folder (ex: /docs) used to resolve absolute links to local files
             skip_external: Whether or not to skip checking external (http..) links
         """
-        self._docs_path = docs_path.strip(os.path.sep)
-        self._docs_root = docs_root.strip(os.path.sep)
+        self._docs_path = docs_path
+        self._docs_root = docs_root
         self._site_prefix = site_prefix.strip("/")
         self._skip_external = skip_external
 
@@ -111,7 +111,9 @@ def _is_doc_link(self, markdown_link: str) -> bool:
     def _is_anchor_link(self, link: str) -> bool:
         return link.startswith("#")
 
-    def _check_external_link(self, link: str, file: str) -> Optional[LinkReport]:
+    def _check_external_link(
+        self, link: str, file: pathlib.Path
+    ) -> Optional[LinkReport]:
         if self._skip_external:
             return None
 
@@ -142,23 +144,24 @@ def _check_external_link(self, link: str, file: str) -> Optional[LinkReport]:
                 link, file, f"External link raised a connection error {err.errno}"
             )
 
-    def _get_os_path(self, path: str) -> str:
-        """Gets an os-specific path from a path found in a markdown file"""
-        return path.replace("/", os.path.sep)
-
-    def _get_absolute_path(self, path: str) -> str:
-        return os.path.join(self._docs_root, self._get_os_path(path))  # noqa: PTH118
+    def _get_absolute_path(self, path: pathlib.Path) -> pathlib.Path:
+        return self._docs_root.joinpath(path).resolve()
 
-    def _get_relative_path(self, file: str, path: str) -> str:
+    def _get_relative_path(
+        self, file: pathlib.Path, path: pathlib.Path
+    ) -> pathlib.Path:
         # link should be relative to the location of the current file
-        directory = os.path.dirname(file)  # noqa: PTH120
-        return os.path.join(directory, self._get_os_path(path))  # noqa: PTH118
+        return file.parent / path
 
-    def _get_docroot_path(self, path: str) -> str:
-        return os.path.join(self._docs_root, self._get_os_path(path))  # noqa: PTH118
+    def _get_docroot_path(self, path: pathlib.Path) -> pathlib.Path:
+        return self._docs_path / path
 
     def _check_absolute_link(
-        self, link: str, file: str, path: str, version: Optional[str]
+        self,
+        link: str,
+        file: pathlib.Path,
+        path: pathlib.Path | str,
+        version: Optional[str],
     ) -> Optional[LinkReport]:
         logger.debug(f"Checking absolute link {link} in file {file}")
 
@@ -167,71 +170,73 @@ def _check_absolute_link(
             return None
 
         # absolute links should point to files that exist (with the .md extension added)
-        md_file = self._get_absolute_path(path).rstrip("/") + ".md"
+        md_file = pathlib.Path(path).resolve().with_suffix(".md")
         logger.debug(f"Absolute link {link} resolved to path {md_file}")
 
-        if not os.path.isfile(md_file):  # noqa: PTH113
+        if not md_file.is_file():
             logger.info(f"Absolute link {link} in file {file} was not found")
             return LinkReport(link, file, f"Linked file {md_file} not found")
         else:
             logger.debug(f"Absolute link {link} in file {file} found")
             return None
 
     def _check_absolute_image(
-        self, link: str, file: str, path: str
+        self, link: str, file: pathlib.Path, path: pathlib.Path
     ) -> Optional[LinkReport]:
         logger.debug(f"Checking absolute image {link} in file {file}")
 
         image_file = self._get_absolute_path(path)
-        if not os.path.isfile(image_file):  # noqa: PTH113
+        if not image_file.is_file():
             logger.info(f"Absolute image {link} in file {file} was not found")
             return LinkReport(link, file, f"Image {image_file} not found")
         else:
             logger.debug(f"Absolute image {link} in file {file} found")
             return None
 
     def _check_relative_link(
-        self, link: str, file: str, path: str
+        self, link: str, file: pathlib.Path, path: pathlib.Path
     ) -> Optional[LinkReport]:
         logger.debug(f"Checking relative link {link} in file {file}")
 
         md_file = self._get_relative_path(file, path)
         logger.debug(f"Relative link {link} resolved to path {md_file}")
 
-        if not os.path.isfile(md_file):  # noqa: PTH113
+        if not md_file.is_file():
             logger.info(f"Relative link {link} in file {file} was not found")
             return LinkReport(link, file, f"Linked file {md_file} not found")
         else:
             logger.debug(f"Relative link {link} in file{file} found")
             return None
 
     def _check_relative_image(
-        self, link: str, file: str, path: str
+        self, link: str, file: pathlib.Path, path: pathlib.Path
     ) -> Optional[LinkReport]:
         logger.debug(f"Checking relative image {link} in file {file}")
 
         image_file = self._get_relative_path(file, path)
-        if not os.path.isfile(image_file):  # noqa: PTH113
+        if not image_file.is_file():
             logger.info(f"Relative image {link} in file {file} was not found")
             return LinkReport(link, file, f"Image {image_file} not found")
         else:
             logger.debug(f"Relative image {link} in file {file} found")
             return None
 
     def _check_docroot_link(
-        self, link: str, file: str, path: str
+        self, link: str, file: pathlib.Path, path: pathlib.Path
     ) -> Optional[LinkReport]:
         logger.debug(f"Checking docroot link {link} in file {file}")
 
         md_file = self._get_docroot_path(path)
-        if not os.path.isfile(md_file):  # noqa: PTH113
+        if not md_file.is_file():
             logger.info(f"Docroot link {link} in file {file} was not found")
             return LinkReport(link, file, f"Linked file {md_file} not found")
         else:
             logger.debug(f"Docroot link {link} in file {file} found")
             return None
 
-    def _check_link(self, match: re.Match, file: str) -> Optional[LinkReport]:
+    def _check_link(  # noqa: PLR0912 # too complex
+        self, match: re.Match, file: pathlib.Path
+    ) -> Optional[LinkReport]:
         """Checks that a link is valid. Valid links are:
         - Absolute links that begin with a forward slash and the specified site prefix (ex: /docs) with no suffix
         - Absolute images with an image suffix
@@ -285,7 +290,7 @@ def _check_link(self, match: re.Match, file: str) -> Optional[LinkReport]:
 
         return result
 
-    def check_file(self, file: str) -> List[LinkReport]:
+    def check_file(self, file: pathlib.Path) -> List[LinkReport]:
         """Looks for all the links in a file and checks them.
 
         Returns:
@@ -319,14 +324,14 @@ def check_file(self, file: str) -> List[LinkReport]:
 @click.option(
     "--path",
     "-p",
-    type=click.Path(exists=True, file_okay=True),
+    type=click.Path(exists=True, file_okay=True, path_type=pathlib.Path),
     default=".",
     help="Path to markdown file(s) to check",
 )
 @click.option(
     "--docs-root",
     "-r",
-    type=click.Path(exists=True, file_okay=False),
+    type=click.Path(exists=True, file_okay=False, path_type=pathlib.Path),
     default=None,
     help="Root to all docs for link checking",
 )
@@ -338,32 +343,38 @@ def check_file(self, file: str) -> List[LinkReport]:
 )
 @click.option("--skip-external", is_flag=True)
 def scan_docs_click(
-    path: str, docs_root: Optional[str], site_prefix: str, skip_external: bool
+    path: pathlib.Path,
+    docs_root: Optional[pathlib.Path],
+    site_prefix: str,
+    skip_external: bool,
 ) -> None:
     code, message = scan_docs(path, docs_root, site_prefix, skip_external)
     click.echo(message)
-    exit(code)
+    sys.exit(code)
 
 
 def scan_docs(
-    path: str, docs_root: Optional[str], site_prefix: str, skip_external: bool
+    path: pathlib.Path,
+    docs_root: pathlib.Path | None,
+    site_prefix: str,
+    skip_external: bool,
 ) -> tuple[int, str]:
-    if docs_root is None:
+    if not docs_root:
         docs_root = path
-    elif not os.path.isdir(docs_root):  # noqa: PTH112
+    elif not docs_root.is_dir():
         return 1, f"Docs root path: {docs_root} is not a directory"
 
     # prepare our return value
-    result: List[LinkReport] = list()
+    result: List[LinkReport] = []
     checker = LinkChecker(path, docs_root, site_prefix, skip_external)
 
-    if os.path.isdir(path):  # noqa: PTH112
+    if path.is_dir():
         # if the path is a directory, get all .md files within it
-        for file in glob.glob(f"{path}/**/*.md", recursive=True):
+        for file in path.rglob("*.md"):
             report = checker.check_file(file)
             if report:
                 result.extend(report)
-    elif os.path.isfile(path):  # noqa: PTH113
+    elif path.is_file():
         # else we support checking one file at a time
         result.extend(checker.check_file(path))
     else:

docs/prepare_prior_versions.py

@@ -4,7 +4,6 @@
 """
 from __future__ import annotations
 
-import glob
 import pathlib
 import re
 
@@ -21,7 +20,7 @@ def change_paths_for_docs_file_references(verbose: bool = False) -> None:
     snippets only for v0.15.50 and later.
     """
     path = _docs_dir() / "docusaurus/versioned_docs/version-0.14.13/"
-    files = glob.glob(f"{path}/**/*.md", recursive=True)
+    files = list(path.rglob("*.md"))
     pattern = re.compile(r"((.*)(file *= *)((../)*))(.*)")
     path_to_insert = "versioned_code/version-0.14.13/"
 
@@ -88,9 +87,9 @@ def prepend_version_info_to_name_for_snippet_by_name_references(
     )
     for path in paths:
         version = path.name
-        files = []
+        files: list[pathlib.Path] = []
         for extension in (".md", ".mdx", ".py", ".yml", ".yaml"):
-            files.extend(glob.glob(f"{path}/**/*{extension}", recursive=True))
+            files.extend(path.rglob(f"*{extension}"))
         print(
             f"    Processing {len(files)} files for path {path} in prepend_version_info_to_name_for_snippet_by_name_references..."
         )
@@ -129,9 +128,9 @@ def prepend_version_info_to_name_for_href_absolute_links(verbose: bool = False)
         if not version_only:
             raise ValueError("Path does not contain a version number")
 
-        files = []
+        files: list[pathlib.Path] = []
         for extension in (".md", ".mdx"):
-            files.extend(glob.glob(f"{path}/**/*{extension}", recursive=True))
+            files.extend(path.rglob(f"**/*{extension}"))
         print(
             f"    Processing {len(files)} files for path {path} in prepend_version_info_to_name_for_href_absolute_links..."
         )
@@ -345,9 +344,9 @@ def prepend_version_info_to_name_for_md_relative_links(verbose: bool = False) ->
         if not version_only:
             raise ValueError("Path does not contain a version number")
 
-        files = []
+        files: list[pathlib.Path] = []
         for extension in (".md", ".mdx"):
-            files.extend(glob.glob(f"{path}/**/*{extension}", recursive=True))
+            path.rglob(f"**/*{extension}")
         print(
             f"    Processing {len(files)} files for path {path} in {method_name_for_logging}..."
         )
@@ -357,7 +356,7 @@ def prepend_version_info_to_name_for_md_relative_links(verbose: bool = False) ->
             "_data_docs_build_and_view.md",
             "_checkpoint_create_and_run.md",
         ]
-        files = [file for file in files if file.split("/")[-1] in files_to_process]
+        files = [file for file in files if file.name in files_to_process]
         for file_path in files:
             with open(file_path, "r+") as f:
                 contents = f.read()

docs/ruff.toml

@@ -0,0 +1,12 @@
+# docs/ specific ruff linter overrides
+
+# root linter settings are defined in the file below
+extend = "../pyproject.toml"
+
+extend-ignore = [
+    # https://docs.astral.sh/ruff/rules/magic-value-comparison/
+    "PLR2004", # can be tedious and overly verbose in docs
+]
+
+[isort]
+known-first-party = ["great_expectations", "tests"]

docs/sphinx_api_docs_source/build_sphinx_api_docs.py

@@ -165,7 +165,7 @@ def _create_mdx_files_for_docusaurus_from_sphinx_html(self) -> None:
         # Read the generated html and process the content for conversion to mdx
         # Write out to .mdx file using the relative file directory structure
         for html_file_path in self._get_generated_html_file_paths():
-            logger.debug(f"Processing: {str(html_file_path.absolute())}")
+            logger.debug(f"Processing: {html_file_path.absolute()!s}")
             with open(html_file_path.absolute()) as f:
                 html_file_contents = f.read()
                 doc_str = self._parse_and_process_html_to_mdx(
@@ -177,7 +177,7 @@ def _create_mdx_files_for_docusaurus_from_sphinx_html(self) -> None:
                     sidebar_entry=self._get_sidebar_entry(html_file_path=html_file_path)
                 )
                 output_path.parent.mkdir(parents=True, exist_ok=True)
-                logger.debug(f"Writing out mdx file: {str(output_path.absolute())}")
+                logger.debug(f"Writing out mdx file: {output_path.absolute()!s}")
                 with open(output_path, "w") as fout:
                     fout.write(doc_str)
 
@@ -207,7 +207,7 @@ def _parse_and_process_html_to_mdx(
         Returns:
             Content suitable for use in a docusaurus mdx file.
         """
-        from bs4 import (
+        from bs4 import (  # noqa: I001
             BeautifulSoup,
         )  # Importing here since it is not a library requirement
 
@@ -234,7 +234,9 @@ def _parse_and_process_html_to_mdx(
         doc["class"] = "sphinx-api-doc"
 
         # Change style to styles to avoid rendering errors
-        tags_with_style = doc.find_all("col", style=lambda value: value in value)
+        tags_with_style = doc.find_all(
+            "col", style=lambda value: value in value  # noqa: PLR0124
+        )
         for tag in tags_with_style:
             style = tag["style"]
             del tag["style"]
@@ -592,7 +594,10 @@ def _clean_up_code_blocks(self, doc: str) -> str:
         """
         doc = doc.replace("&lt;", "<").replace("&gt;", ">")
         doc = (
-            doc.replace("“", '"').replace("”", '"').replace("‘", "'").replace("’", "'")
+            doc.replace("“", '"')
+            .replace("”", '"')
+            .replace("‘", "'")  # noqa: RUF001
+            .replace("’", "'")  # noqa: RUF001
         )
         doc = doc.replace("<cite>{", "`").replace("}</cite>", "`")
         doc = doc.replace("${", r"\${")

docs/sphinx_api_docs_source/check_public_api_docstrings.py

@@ -111,6 +111,7 @@ def run_ruff(paths: List[pathlib.Path]) -> List[str]:
         cmds,
         capture_output=True,
         text=True,
+        check=False,
     )
 
     # Check to make sure `ruff` actually ran
@@ -124,7 +125,7 @@ def run_ruff(paths: List[pathlib.Path]) -> List[str]:
 
 def _log_with_timestamp(content: str) -> None:
     """Log content with timestamp appended."""
-    timestamp = datetime.datetime.now()
+    timestamp = datetime.datetime.now()  # noqa: DTZ005
     timestamp_str = timestamp.strftime("%H:%M:%S")
     logger.debug(f"{content} Timestamp: {timestamp_str}")