Autodocs and more!

README.md

@@ -1,2 +1,28 @@
 # salt-extension
 Tool to simplify the creation of a new salt extension
+
+## Quickstart
+
+The best way to use this project is with [pipx][pipx]:
+
+    $ pipx install salt-extension
+    $ mkdir my_extension
+    $ cd my_extension
+    $ create-salt-extension my_extension -l states -l module
+    Author: John Example Doe
+    Author email: [email protected]
+    Summary: An example Salt Extension Module
+    Url: https://example.com/my-saltext
+    License (apache, other): apache
+
+Then follow the other output instructions.
+
+If all goes well, you should be able to run:
+
+    $ salt-call --local my_extension.example_function text="it worked!"
+    local:
+        it worked!
+
+Happy hacking!
+
+[pipx]: https://pypi.org/project/pipx/

src/saltext/cli/__main__.py

@@ -284,15 +284,16 @@ def main(
     )
     click.secho(f"  rm src/saltext/{package_name}/loader.py")
     click.secho("You should now run the following commands:")
-    click.secho("  pip install pre-commit nox")
+    click.secho(f"  python3 -m venv .env --prompt {project_name!r}")
+    click.secho("  source .env/bin/activate")
     click.secho("  git init .")
-    click.secho("  git add .")
+    click.secho("  python -m pip install -e .[dev,tests,docs]")
     click.secho("  pre-commit install")
+    click.secho("  git add .")
     click.secho("  git commit -a")
     click.secho("The above command will fail because it's pinning the project dependencies.")
     click.secho("Now run the following commands:")
-    click.secho("  nox -e gen-api-docs")
-    click.secho("  git add docs/ref")
+    click.secho("  git add .")
     click.secho("  git commit -a -m 'Initial extension layout'")
     click.secho("To run the included test suite, run the following command:")
     click.secho("  nox -e tests-3 -- tests/")

src/saltext/cli/project/.pre-commit-config.yaml.j2

@@ -27,6 +27,14 @@ repos:
         language: system
         files: ^src/saltext/{{ package_name }}/modules/.*\.py$
 
+  - repo: local
+    hooks:
+      - id: check-docs
+        name: Check rST doc files exist for modules/states
+        entry: python .pre-commit-hooks/make-autodocs.py
+        language: system
+        pass_filenames: false
+
   - repo: https://github.com/s0undt3ch/salt-rewrite
     # Automatically rewrite code with known rules
     rev: 1.3.2

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

@@ -0,0 +1,79 @@
+import sys
+from enum import IntEnum
+from pathlib import Path
+
+
+class Result(IntEnum):
+    success = 0
+    fail = 1
+
+
+result = Result.fail
+
+all_states = []
+all_mods = []
+docs_path = Path("docs")
+ref_path = docs_path / "ref"
+mod_path = ref_path / "modules"
+state_path = ref_path / "states"
+
+for path in Path("src").glob("**/*.py"):
+    if path.parent.name in ("states", "modules"):
+        kind = path.parent.name
+        import_path = ".".join(path.with_suffix("").parts[1:])
+        if kind == "states":
+            all_states.append(import_path)
+            rst_path = state_path / (import_path + ".rst")
+        elif kind == "modules":
+            all_mods.append(import_path)
+            rst_path = mod_path / (import_path + ".rst")
+
+        rst_path.parent.mkdir(parents=True, exist_ok=True)
+        rst_path.write_text(
+            f"""
+{import_path}
+{'='*len(import_path)}
+
+.. automodule:: {import_path}
+    :members:
+"""
+        )
+
+        # print(import_path)
+        # print(kind, path)
+
+states_rst = state_path / "all.rst"
+states_rst.parent.mkdir(parents=True, exist_ok=True)
+mods_rst = mod_path / "all.rst"
+mods_rst.parent.mkdir(parents=True, exist_ok=True)
+
+
+mods_rst.write_text(
+    f"""
+.. all-saltext.vmware.modules:
+
+-----------------
+Execution Modules
+-----------------
+
+.. autosummary::
+    :toctree:
+
+{chr(10).join(sorted('    '+mod for mod in all_mods))}
+"""
+)
+states_rst.write_text(
+    f"""
+.. all-saltext.vmware.states:
+
+-------------
+State Modules
+-------------
+
+.. autosummary::
+    :toctree:
+
+{chr(10).join(sorted('    '+state for state in all_states))}
+"""
+)
+# exit(result)

src/saltext/cli/project/README.md.j2

@@ -1,2 +1,33 @@
 # {{ project_name }}
+
 {{ summary }}
+
+## Quickstart
+
+To get started with your new project:
+
+    # Create a new venv
+    python3 -m venv env --prompt {{ project_name }}
+    source env/bin/activate
+
+    # On mac, you may need to upgrade pip
+    python -m pip install --upgrade pip
+
+    # On WSL or some flavors of linux you may need to install the `enchant`
+    # library in order to build the docs
+    sudo apt-get install -y enchant
+
+    # Install extension + test/dev/doc dependencies into your environment
+    python -m pip install -e .[tests,dev,docs]
+
+    # Run tests!
+    python -m nox -e tests-3
+
+    # skip requirements install for next time
+    export SKIP_REQUIREMENTS_INSTALL=1
+
+    # Build the docs, serve, and view in your web browser:
+    python -m nox -e docs && (cd docs/_build/html; python -m webbrowser localhost:8000; python -m http.server; cd -)
+
+    # Run the example function
+    salt-call --local {{ project_name }}.example_function text="Happy Hacking!"

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

@@ -0,0 +1,18 @@
+{%- set header = "Complete List of {}".format(project_name) %}
+{%- set header_ruler = "=" * header|length -%}
+.. _all the states/modules:
+
+{{ header }}
+{{ header_ruler }}
+
+
+.. toctree::
+   :maxdepth: 2
+
+   ref/modules/all.rst
+
+
+.. toctree::
+   :maxdepth: 2
+
+   ref/states/all.rst

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

@@ -7,11 +7,7 @@
   :maxdepth: 2
   :caption: Contents:
 
-  ref/saltext.{{ package_name }}.rst
-{%- for loader_package in loader_packages %}
-  ref/saltext.{{ package_name }}.{{ loader_package }}.rst
-{%- endfor %}
-  ref/modules.rst
+  all.rst
 
 Indices and tables
 ==================

src/saltext/cli/project/noxfile.py.j2

@@ -28,7 +28,7 @@ SKIP_REQUIREMENTS_INSTALL = "SKIP_REQUIREMENTS_INSTALL" in os.environ
 EXTRA_REQUIREMENTS_INSTALL = os.environ.get("EXTRA_REQUIREMENTS_INSTALL")
 
 COVERAGE_VERSION_REQUIREMENT = "coverage==5.2"
-SALT_REQUIREMENT = os.environ.get("SALT_REQUIREMENT") or "salt>=3002.6"
+SALT_REQUIREMENT = os.environ.get("SALT_REQUIREMENT") or "salt>=3003rc1"
 if SALT_REQUIREMENT == "salt==master":
     SALT_REQUIREMENT = "git+https://github.com/saltstack/salt.git@master"
 
@@ -81,7 +81,9 @@ def _install_requirements(
     install_test_requirements=True,
     install_source=False,
     install_salt=True,
+    install_extras=None,
 ):
+    install_extras = install_extras or []
     if SKIP_REQUIREMENTS_INSTALL is False:
         # Always have the wheel package installed
         session.install("--progress-bar=off", "wheel", silent=PIP_INSTALL_SILENT)
@@ -91,18 +93,10 @@ def _install_requirements(
             )
 
         if install_salt:
-            session.install(
-                "--progress-bar=off", SALT_REQUIREMENT, silent=PIP_INSTALL_SILENT
-            )
+            session.install("--progress-bar=off", SALT_REQUIREMENT, silent=PIP_INSTALL_SILENT)
 
         if install_test_requirements:
-            requirements_file = REPO_ROOT / "requirements" / _get_pydir(session) / "tests.txt"
-            install_command = [
-                "--progress-bar=off",
-                "-r",
-                str(requirements_file.relative_to(REPO_ROOT)),
-            ]
-            session.install(*install_command, silent=PIP_INSTALL_SILENT)
+            install_extras.append("tests")
 
         if EXTRA_REQUIREMENTS_INSTALL:
             session.log(
@@ -113,12 +107,16 @@ def _install_requirements(
             )
             install_command = ["--progress-bar=off"]
             install_command += [req.strip() for req in EXTRA_REQUIREMENTS_INSTALL.split()]
-            session.install(*install_command, silent=PIP_INSTALL_SILENT)
+            session.install(*passed_requirements, silent=PIP_INSTALL_SILENT)
 
-        if passed_requirements:
-            session.install(*passed_requirements)
         if install_source:
-            session.install("-e", ".", silent=PIP_INSTALL_SILENT)
+            pkg = "."
+            if install_extras:
+                pkg += f"[{','.join(install_extras)}]"
+            session.install("-e", pkg, silent=PIP_INSTALL_SILENT)
+        elif install_extras:
+            pkg = f".[{','.join(install_extras)}]"
+            session.install(pkg, silent=PIP_INSTALL_SILENT)
 
 
 @nox.session(python=PYTHON_VERSIONS)
@@ -208,16 +206,13 @@ def tests(session):
             "--include=tests/*",
         )
         try:
-            session.run(
-                "coverage", "report", "--show-missing",
-                "--include=src/saltext/{{ package_name }}/*"
-            )
+            session.run("coverage", "report", "--show-missing", "--include=src/saltext/{{ package_name }}/*")
             # If you also want to display the code coverage report on the CLI
             # for the tests, comment the call above and uncomment the line below
-            #session.run(
+            # session.run(
             #    "coverage", "report", "--show-missing",
             #    "--include=src/saltext/{{ package_name }}/*,tests/*"
-            #)
+            # )
         finally:
             # Move the coverage DB to artifacts/coverage in order for it to be archived by CI
             if COVERAGE_REPORT_DB.exists():
@@ -245,8 +240,13 @@ class Tee:
 
 
 def _lint(session, rcfile, flags, paths, tee_output=True):
-    requirements_file = REPO_ROOT / "requirements" / _get_pydir(session) / "lint.txt"
-    _install_requirements(session, "-r", str(requirements_file.relative_to(REPO_ROOT)))
+    _install_requirements(
+        session,
+        install_salt=False,
+        install_coverage_requirements=False,
+        install_test_requirements=False,
+        install_extras=["dev", "tests"],
+    )
 
     if tee_output:
         session.run("pylint", "--version")
@@ -389,14 +389,12 @@ def docs(session):
     """
     Build Docs
     """
-    requirements_file = REPO_ROOT / "requirements" / _get_pydir(session) / "docs.txt"
     _install_requirements(
         session,
-        "-r",
-        str(requirements_file.relative_to(REPO_ROOT)),
         install_coverage_requirements=False,
         install_test_requirements=False,
         install_source=True,
+        install_extras=["docs"],
     )
     os.chdir("docs/")
     session.run("make", "clean", external=True)
@@ -417,14 +415,12 @@ def docs_crosslink_info(session):
     """
     Report intersphinx cross links information
     """
-    requirements_file = REPO_ROOT / "requirements" / _get_pydir(session) / "docs.txt"
     _install_requirements(
         session,
-        "-r",
-        str(requirements_file.relative_to(REPO_ROOT)),
         install_coverage_requirements=False,
         install_test_requirements=False,
         install_source=True,
+        install_extras=["docs"],
     )
     os.chdir("docs/")
     intersphinx_mapping = json.loads(
@@ -456,22 +452,25 @@ def docs_crosslink_info(session):
     os.chdir(str(REPO_ROOT))
 
 
-
 @nox.session(name="gen-api-docs", python="3")
 def gen_api_docs(session):
     """
     Generate API Docs
     """
-    requirements_file = REPO_ROOT / "requirements" / _get_pydir(session) / "docs.txt"
     _install_requirements(
         session,
-        "-r",
-        str(requirements_file.relative_to(REPO_ROOT)),
         install_coverage_requirements=False,
         install_test_requirements=False,
         install_source=True,
+        install_extras=["docs"],
     )
     shutil.rmtree("docs/ref")
     session.run(
-        "sphinx-apidoc", "--implicit-namespaces", "--module-first", "-o", "docs/ref/", "src/saltext"
+        "sphinx-apidoc",
+        "--implicit-namespaces",
+        "--module-first",
+        "-o",
+        "docs/ref/",
+        "src/saltext",
+        "src/saltext/{{ package_name }}/config/schemas",
     )