Merge pull request #10 from lkubb/docs-improvements

.copier-answers.yml

@@ -1,6 +1,6 @@
 # Autogenerated. Do not edit this by hand, use `copier update`.
 ---
-_commit: 0.2.4
+_commit: 0.2.5
 _src_path: https://github.com/lkubb/salt-extension-copier
 author: jeanluc
 author_email: [email protected]

.pre-commit-hooks/check-cli-examples.py

@@ -4,7 +4,7 @@
 import sys
 
 CODE_ROOT = pathlib.Path(__file__).resolve().parent.parent
-EXECUTION_MODULES_PATH = CODE_ROOT / "src" / "saltext" / " pushover" / "modules"
+EXECUTION_MODULES_PATH = CODE_ROOT / "src" / "saltext" / "pushover" / "modules"
 
 
 def check_cli_examples(files):

.pre-commit-hooks/make-autodocs.py

@@ -1,21 +1,43 @@
+import ast
 import subprocess
 from pathlib import Path
 
 
 repo_path = Path(subprocess.check_output(["git", "rev-parse", "--show-toplevel"]).decode().strip())
-src_dir = repo_path / "src" / " saltext" / "pushover"
+src_dir = repo_path / "src" / "saltext" / "pushover"
 doc_dir = repo_path / "docs"
 
 docs_by_kind = {}
 changed_something = False
 
 
-def write_module(rst_path, import_path):
+def _find_virtualname(path):
+    tree = ast.parse(path.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and target.id == "__virtualname__":
+                    if isinstance(node.value, ast.Str):
+                        virtualname = node.value.s
+                        break
+            else:
+                continue
+            break
+    else:
+        virtualname = path.with_suffix("").name
+    return virtualname
+
+
+def write_module(rst_path, path, use_virtualname=True):
+    if use_virtualname:
+        virtualname = "``" + _find_virtualname(path) + "``"
+    else:
+        virtualname = make_import_path(path)
     module_contents = f"""\
-{import_path}
-{'='*len(import_path)}
+{virtualname}
+{'='*len(virtualname)}
 
-.. automodule:: {import_path}
+.. automodule:: {make_import_path(path)}
     :members:
 """
     if not rst_path.exists() or rst_path.read_text() != module_contents:
@@ -26,9 +48,12 @@ def write_module(rst_path, import_path):
 
 
 def write_index(index_rst, import_paths, kind):
-    header_text = (
-        "execution modules" if kind.lower() == "modules" else kind.rstrip("s") + " modules"
-    )
+    if kind.rstrip("s") == "util":
+        header_text = "Utilities"
+    else:
+        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)}"
     index_contents = f"""\
 .. all-saltext.pushover.{kind}:
@@ -67,7 +92,7 @@ def 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)
+        change = write_module(rst_path, path, use_virtualname=kind != "utils")
         changed_something = changed_something or change
 
     write_index(index_rst, import_paths, kind)

docs/changelog.md

@@ -0,0 +1,12 @@
+# Changelog
+
+The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH
+
+```{towncrier-draft-entries}
+```
+
+```{include} ../CHANGELOG.md
+:start-after: '# Changelog'
+```

docs/conf.py

@@ -12,6 +12,7 @@
 import email.policy
 import os
 import sys
+from pathlib import Path
 
 try:
     from importlib_metadata import distribution
@@ -26,6 +27,8 @@
     # assume we're in the doc/ directory
     docs_basepath = os.path.abspath(os.path.dirname("."))
 
+PROJECT_ROOT_DIR = Path(docs_basepath).parent
+
 addtl_paths = (
     os.path.join(os.pardir, "src"),  # saltext.pushover itself (for autodoc)
     "_ext",  # custom Sphinx extensions
@@ -89,6 +92,14 @@
     "sphinx.ext.coverage",
     "sphinx_copybutton",
     "sphinxcontrib.spelling",
+    "sphinxcontrib.towncrier.ext",
+    "myst_parser",
+]
+
+myst_extensions = [
+    "colon_fence",
+    "deflist",
+    "tasklist",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -160,6 +171,11 @@
 autodoc_mock_imports = ["salt"]
 # <---- Autodoc Config -----------------------------------------------------------------------------------------------
 
+# Towncrier draft config
+towncrier_draft_autoversion_mode = "sphinx-release"
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = str(PROJECT_ROOT_DIR)
+
 
 def setup(app):
     app.add_crossref_type(

docs/index.rst

@@ -1,11 +1,25 @@
-Welcome to pushover Documentation!
-==================================
+``saltext-pushover``: Integrate Salt with Pushover
+==================================================
+
+Salt Extension for interacting with Pushover
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Provided Modules
+  :hidden:
+
+  ref/modules/index
+  ref/returners/index
+  ref/states/index
+  ref/utils/index
 
 .. toctree::
   :maxdepth: 2
-  :caption: Contents:
+  :caption: News
+  :hidden:
+
+  changelog
 
-  all.rst
 
 Indices and tables
 ==================

docs/ref/modules/saltext.pushover.modules.pushover_notify.rst

@@ -1,5 +1,5 @@
-saltext.pushover.modules.pushover_notify
-========================================
+``pushover``
+============
 
 .. automodule:: saltext.pushover.modules.pushover_notify
     :members:

docs/ref/returners/saltext.pushover.returners.pushover_returner.rst

@@ -1,5 +1,5 @@
-saltext.pushover.returners.pushover_returner
-============================================
+``pushover``
+============
 
 .. automodule:: saltext.pushover.returners.pushover_returner
     :members:

docs/ref/states/saltext.pushover.states.pushover.rst

@@ -1,5 +1,5 @@
-saltext.pushover.states.pushover
-================================
+``pushover``
+============
 
 .. automodule:: saltext.pushover.states.pushover
     :members:

docs/ref/utils/index.rst

@@ -1,8 +1,8 @@
 .. all-saltext.pushover.utils:
 
-____________
-Util Modules
-____________
+_________
+Utilities
+_________
 
 .. currentmodule:: saltext.pushover.utils
 

pyproject.toml

@@ -61,6 +61,9 @@ docs = [
   "sphinx-prompt",
   "sphinxcontrib-spelling",
   "sphinx-copybutton",
+  "towncrier==22.12.0",
+  "sphinxcontrib-towncrier",
+  "myst_parser",
   "furo",
   "furo<=2023.03.27; python_version < '3.8'",
   "importlib_metadata; python_version < '3.8'",