Docs build fixes

src/saltext/cli/__main__.py

@@ -215,6 +215,7 @@ def main(
         "max_python_minor": max_python_minor,
         "max_salt_version": max_salt_version,
         "salt_python_support": copy.deepcopy(SALT_PYTHON_SUPPORT),
+        "singular_loader_dirs": SINGULAR_MODULE_DIRS,
     }
     if no_saltext_namespace:
         package_namespace = package_namespace_path = package_namespace_pkg = ""

src/saltext/cli/project/.pre-commit-hooks/make-autodocs.py.j2

@@ -1,59 +1,78 @@
 import subprocess
-import sys
-from enum import IntEnum
 from pathlib import Path
 
 
 repo_path = Path(subprocess.check_output(["git", "rev-parse", "--show-toplevel"]).decode().strip())
-src_dir = repo_path / "src" / {% if package_namespace -%}" {{ package_namespace}}" / {% endif -%} "{{ project_name }}"
+src_dir = repo_path / "src" / {% if package_namespace -%}" {{ package_namespace }}" / {% endif -%} "{{ project_name }}"
 doc_dir = repo_path / "docs"
 
 docs_by_kind = {}
+changed_something = False
 
 
-def make_import_path(path):
-    return ".".join(path.with_suffix("").parts[-4:])
-
-
-for path in Path(__file__).parent.parent.joinpath("src/{{ package_namespace_path }}{{ project_name }}/").glob("*/*.py"):
-    if path.name != "__init__.py":
-        kind = path.parent.name
-        docs_by_kind.setdefault(kind, set()).add(path)
-
-for kind in docs_by_kind:
-    kind_path = doc_dir / "ref" / kind
-    all_rst = kind_path / "all.rst"
-    import_paths = []
-    for path in sorted(docs_by_kind[kind]):
-        import_path = make_import_path(path)
-        import_paths.append(import_path)
-        rst_path = kind_path.joinpath(import_path).with_suffix(".rst")
-        print(rst_path)
-        rst_path.parent.mkdir(parents=True, exist_ok=True)
-        rst_path.write_text(
-            f"""
+def write_module(rst_path, import_path):
+    module_contents = f"""\
 {import_path}
 {'='*len(import_path)}
 
 .. automodule:: {import_path}
     :members:
 """
-        )
+    if not rst_path.exists() or rst_path.read_text() != module_contents:
+        print(rst_path)
+        rst_path.write_text(module_contents)
+        return True
+    return False
+
 
+def write_index(index_rst, import_paths, kind):
     header_text = (
         "execution modules" if kind.lower() == "modules" else kind.rstrip("s") + " modules"
     )
     header = f"{'_'*len(header_text)}\n{header_text.title()}\n{'_'*len(header_text)}"
-
-    all_rst.write_text(
-        f"""
-.. all-{%- if package_namespace %}{{ package_namespace}}.{%- endif %}{{ project_name }}.{kind}:
+    index_contents = f"""\
+.. all-{%- if package_namespace %}{{ package_namespace }}.{%- endif %}{{ project_name }}.{kind}:
 
 {header}
 
+.. currentmodule:: {import_paths[0][:import_paths[0].rfind(".")]}
+
 .. autosummary::
     :toctree:
 
-{chr(10).join(sorted('    '+p for p in import_paths))}
+{chr(10).join(sorted('    '+p[p.rfind(".")+1:] for p in import_paths))}
 """
-    )
+    if not index_rst.exists() or index_rst.read_text() != index_contents:
+        print(index_rst)
+        index_rst.write_text(index_contents)
+        return True
+    return False
+
+
+def make_import_path(path):
+    return ".".join(path.relative_to(repo_path / "src").with_suffix("").parts)
+
+
+for path in src_dir.glob("*/*.py"):
+    if path.name != "__init__.py":
+        kind = path.parent.name
+        docs_by_kind.setdefault(kind, set()).add(path)
+
+for kind in docs_by_kind:
+    kind_path = doc_dir / "ref" / kind
+    index_rst = kind_path / "index.rst"
+    import_paths = []
+    for path in sorted(docs_by_kind[kind]):
+        import_path = make_import_path(path)
+        import_paths.append(import_path)
+        rst_path = kind_path / (import_path + ".rst")
+        rst_path.parent.mkdir(parents=True, exist_ok=True)
+        change = write_module(rst_path, import_path)
+        changed_something = changed_something or change
+
+    write_index(index_rst, import_paths, kind)
+
+
+# Ensure pre-commit realizes we did something
+if changed_something:
+    exit(2)

src/saltext/cli/project/docs/all.rst.j2

@@ -6,13 +6,10 @@
 {{ header_ruler }}
 
 
+{% for loader in loaders %}
 .. toctree::
    :maxdepth: 2
 
-   ref/modules.rst
+   ref/{{ loader.rstrip("s") + ("" if loader in singular_loader_dirs else "s") }}/index
 
-
-.. toctree::
-   :maxdepth: 2
-
-   ref/states.rst
+{% endfor %}

src/saltext/cli/project/docs/conf.py.j2

@@ -95,7 +95,7 @@ exclude_patterns = [
     "sitevars.rst",
 ]
 
-autosummary_generate = True
+autosummary_generate = False
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -136,7 +136,7 @@ napoleon_use_rtype = True
 # ----- Intersphinx Config ---------------------------------------------------------------------------------------->
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "pytest": ("https://pytest.readthedocs.io/en/stable", None),
+    "pytest": ("https://docs.pytest.org/en/stable", None),
     "salt": ("https://docs.saltproject.io/en/latest", None),
 }
 # <---- Intersphinx Config -----------------------------------------------------------------------------------------

src/saltext/cli/project/requirements/docs.in.j2

@@ -2,6 +2,9 @@ sphinx
 sphinx-material-saltstack
 sphinx-prompt
 sphinxcontrib-spelling
+sphinx-copybutton
+furo
 {%- if python_requires < (3, 8) %}
+furo <= 2023.03.27; python_version < "3.8"
 importlib_metadata; python_version < "3.8"
 {%- endif %}