Use the latest skpkg .pre-commit-config.yml (#1243)

* ci: follow new practice of wrtiting commit/issues and news.rst * style: delete unmatched quotes manually to avoid conflicts between black and docformatter * style: apply docformatter to all files in the project
regro · Jan 31, 2025 · 4c244d6 · 4c244d6
1 parent d0a4042
commit 4c244d6
Show file tree

Hide file tree

Showing 80 changed files with 518 additions and 483 deletions.
diff --git a/.github/ISSUE_TEMPLATE/release_checklist.md b/.github/ISSUE_TEMPLATE/release_checklist.md
@@ -6,23 +6,41 @@ labels: "release"
 assignees: ""
 ---
 
-### Release checklist for GitHub contributors
+### PyPI/GitHub rc-release preparation checklist:
 
 - [ ] All PRs/issues attached to the release are merged.
 - [ ] All the badges on the README are passing.
 - [ ] License information is verified as correct. If you are unsure, please comment below.
 - [ ] Locally rendered documentation contains all appropriate pages, including API references (check no modules are
-  missing), tutorials, and other human written text is up-to-date with any changes in the code.
-- [ ] Installation instructions in the README, documentation and on the website (e.g., diffpy.org) updated.
-- [ ] Successfully run any tutorial examples or do functional testing with the latest Python version
-- [ ] Grammar and writing quality have been checked (no typos).
+      missing), tutorials, and other human-written text is up-to-date with any changes in the code.
+- [ ] Installation instructions in the README, documentation, and the website (e.g., diffpy.org) are updated.
+- [ ] Successfully run any tutorial examples or do functional testing with the latest Python version.
+- [ ] Grammar and writing quality are checked (no typos).
+- [ ] Install `pip install build twine`, run `python -m build` and `twine check dist/*` to ensure that the package can be built and is correctly formatted for PyPI release.
 
-Please mention @sbillinge when you are ready for release. Include any additional comments necessary, such as
-version information and details about the pre-release here:
+Please mention @sbillinge here when you are ready for PyPI/GitHub release. Include any additional comments necessary, such as version information and details about the pre-release here:
+
+### PyPI/GitHub full-release preparation checklist:
+
+- [ ] Create a new conda environment and install the rc from PyPI (`pip install <package-name>==??`)
+- [ ] License information on PyPI is correct.
+- [ ] Docs are deployed successfully to `https://www.diffpy.org/<package-name>`.
+- [ ] Successfully run all tests, tutorial examples or do functional testing.
+
+Please let @sbillinge know that all checks are done and the package is ready for full release.
+
+### conda-forge release preparation checklist:
+
+<!-- After @sbillinge releases the PyPI package, please check the following when creating a PR for conda-forge release.-->
+
+- [ ] Ensure that the full release has appeared on PyPI successfully.
+- [ ] New package dependencies listed in `conda.txt` and `test.txt` are added to `meta.yaml` in the feedstock.
+- [ ] Close any open issues on the feedstock. Reach out to @bobleesj if you have questions.
+- [ ] Tag @sbillinge and @bobleesj for conda-forge release.
 
 ### Post-release checklist
 
-Before closing this issue, please complete the following:
+<!-- Before closing this issue, please complete the following: -->
 
 - [ ]  Run tutorial examples and conduct functional testing using the installation guide in the README.
 - [ ]  Documentation (README, tutorials, API references, and websites) is deployed without broken links or missing figures.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,14 +1,14 @@
 default_language_version:
-    python: python3
+  python: python3
 ci:
-    autofix_commit_msg: |
-        [pre-commit.ci] auto fixes from pre-commit hooks
-    autofix_prs: true
-    autoupdate_branch: 'pre-commit-autoupdate'
-    autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
-    autoupdate_schedule: monthly
-    skip: [no-commit-to-branch]
-    submodules: false
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit hooks
+  autofix_prs: true
+  autoupdate_branch: "pre-commit-autoupdate"
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
+  autoupdate_schedule: monthly
+  skip: [no-commit-to-branch]
+  submodules: false
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
@@ -46,9 +46,25 @@ repos:
         name: Prevent Commit to Main Branch
         args: ["--branch", "main"]
         stages: [pre-commit]
+  # codespell - spell checker for source code
   - repo: https://github.com/codespell-project/codespell
     rev: v2.3.0
     hooks:
-    - id: codespell
-      additional_dependencies:
-        - tomli
+      - id: codespell
+        additional_dependencies:
+          - tomli
+  # prettier - multi formatter for json, yaml, md
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: f12edd9c7be1c20cfa42420fd0e6df71e42b51ea # frozen: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        exclude: '.*\.(html|json|css|js|yml|yaml|md)$'
+        additional_dependencies:
+          - "prettier@^3.2.4"
+  # docformatter - formats docstrings using PEP 257
+  - repo: https://github.com/s-weigand/docformatter
+    rev: 5757c5190d95e5449f102ace83df92e7d3b06c6c
+    hooks:
+      - id: docformatter
+        additional_dependencies: [tomli]
+        args: [--in-place, --config, ./pyproject.toml]
diff --git a/news/doc-format.rst b/news/doc-format.rst
@@ -0,0 +1,24 @@
+**Added:**
+
+* 'prettier' and 'docformatter' added to .pre-commit-configs.yml
+* PyPI/Github full-release nd conda-forge release checklist added.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>
diff --git a/src/regolith/broker.py b/src/regolith/broker.py
@@ -1,4 +1,4 @@
-"""API for accessing the metadata and file storage"""
+"""API for accessing the metadata and file storage."""
 
 import copy
 
@@ -8,15 +8,15 @@
 
 
 def load_db(rc_file="regolithrc.json"):
-    """Create a Broker instance from an rc file"""
+    """Create a Broker instance from an rc file."""
     rc = copy.copy(DEFAULT_RC)
     rc._update(load_rcfile(rc_file))
     filter_databases(rc)
     return Broker(rc)
 
 
 class Broker:
-    """Interface to the database and file storage systems
+    """Interface to the database and file storage systems.
 
     Examples
     --------
@@ -63,12 +63,12 @@ def add_file(self, document, name, filepath):
 
     @classmethod
     def from_rc(cls, rc_file="regolithrc.json"):
-        """Return a Broker instance"""
+        """Return a Broker instance."""
         return load_db(rc_file)
 
     def get_file_path(self, document, name):
         """Get a file from the file storage associated with the document and
-        name
+        name.
 
         Parameters
         ----------

diff --git a/src/regolith/builders/activitylogbuilder.py b/src/regolith/builders/activitylogbuilder.py
@@ -34,7 +34,7 @@
 
 
 class ActivitylogBuilder(LatexBuilderBase):
-    """Build CV from database entries"""
+    """Build CV from database entries."""
 
     btype = "annual-activity"
     needed_colls = [
@@ -54,7 +54,7 @@ class ActivitylogBuilder(LatexBuilderBase):
     ]
 
     def construct_global_ctx(self):
-        """Constructs the global context"""
+        """Constructs the global context."""
         super().construct_global_ctx()
         gtx = self.gtx
         rc = self.rc
@@ -80,7 +80,7 @@ def construct_global_ctx(self):
         gtx["zip"] = zip
 
     def latex(self):
-        """Render latex template"""
+        """Render latex template."""
         rc = self.rc
         group = fuzzy_retrieval(self.gtx["groups"], ["_id", "aka", "name"], rc.groupname)
         if not rc.people:

diff --git a/src/regolith/builders/appraisalbuilder.py b/src/regolith/builders/appraisalbuilder.py
@@ -29,7 +29,7 @@
 
 
 class AppraisalBuilder(LatexBuilderBase):
-    """Build CV from database entries"""
+    """Build CV from database entries."""
 
     btype = "annual-activity"
     needed_colls = [
@@ -45,7 +45,7 @@ class AppraisalBuilder(LatexBuilderBase):
     ]
 
     def construct_global_ctx(self):
-        """Constructs the global context"""
+        """Constructs the global context."""
         super().construct_global_ctx()
         gtx = self.gtx
         rc = self.rc
@@ -66,7 +66,7 @@ def construct_global_ctx(self):
         gtx["zip"] = zip
 
     def latex(self):
-        """Render latex template"""
+        """Render latex template."""
         rc = self.rc
         if not rc.people:
             raise RuntimeError("ERROR: please rerun specifying --people name")

diff --git a/src/regolith/builders/basebuilder.py b/src/regolith/builders/basebuilder.py
@@ -1,4 +1,4 @@
-"""Builder Base Classes"""
+"""Builder Base Classes."""
 
 import os
 from glob import glob
@@ -20,7 +20,7 @@
 
 
 class BuilderBase(object):
-    """Base class for builders"""
+    """Base class for builders."""
 
     def __init__(self, rc):
         self.rc = rc
@@ -43,7 +43,7 @@ def __init__(self, rc):
         self.cmds = []
 
     def construct_global_ctx(self):
-        """Constructs the global context"""
+        """Constructs the global context."""
         gtx = self.gtx
         gtx["len"] = len
         gtx["True"] = True
@@ -60,7 +60,7 @@ def construct_global_ctx(self):
         gtx["date_to_rfc822"] = date_to_rfc822
 
     def render(self, tname, fname, **kwargs):
-        """Render the template into a file using the kwargs and global context
+        """Render the template into a file using the kwargs and global context.
 
         Parameters
         ----------
@@ -90,7 +90,7 @@ def build(self):
 
 
 class LatexBuilderBase(BuilderBase):
-    """Base class for Latex builders"""
+    """Base class for Latex builders."""
 
     def __init__(self, rc):
         super().__init__(rc)
@@ -107,11 +107,11 @@ def construct_global_ctx(self):
         gtx["latex_safe_url"] = latex_safe_url
 
     def run(self, cmd):
-        """Run command in build dir"""
+        """Run command in build dir."""
         subprocess.run(cmd, cwd=self.bldir, check=True)
 
     def pdf(self, base):
-        """Compiles latex files to PDF"""
+        """Compiles latex files to PDF."""
         if self.rc.pdf:
             if os.name == "nt":
                 self.run(["pdflatex"] + LATEX_OPTS + [base + ".tex"])
@@ -120,7 +120,7 @@ def pdf(self, base):
                 self.run(["dvipdf", base])
 
     def clean(self):
-        """Remove files created by latex"""
+        """Remove files created by latex."""
         postfixes = [
             "*.dvi",
             "*.toc",

diff --git a/src/regolith/builders/beamplanbuilder.py b/src/regolith/builders/beamplanbuilder.py
@@ -1,8 +1,7 @@
 """Builder for the planning of beamtimes.
 
-The plan contains a summary of the information for the experiments
-in during a beamtime and details about how to carry out the experiments.
-
+The plan contains a summary of the information for the experiments in
+during a beamtime and details about how to carry out the experiments.
 """
 
 from datetime import datetime
@@ -14,8 +13,7 @@
 
 
 class BeamPlanBuilder(LatexBuilderBase):
-    """
-    Build a file of experiment plans for the beamtime from database entries.
+    """Build a file of experiment plans for the beamtime from database entries.
 
     The report is in the '.tex' file. The template of the file is in the
     'templates/beamplan.tex'. The data will be grouped
@@ -60,9 +58,8 @@ def _search(db, key):
         return None
 
     def _gather_info(self, bt, docs):
-        """
-        Query information from the list of documents. Return a table as the summary of the plans and a list of
-        experiment plans.
+        """Query information from the list of documents. Return a table as the
+        summary of the plans and a list of experiment plans.
 
         Parameters
         ----------