Add workflow for pdoc API documentation

Author: ChrisMayfield

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -e .
+      - run: pip install pdoc
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - run: pdoc -o ./docs -d google ./jmu_pytest_utils
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - run postsetup.sh at the end of setup.sh (#11)
 - optional test file argument for builder.py (#12)
 - type hints for all API functions (#13)
+- API documentation website built with pdoc
 
 ### Changed
 

jmu_pytest_utils/__init__.py

@@ -0,0 +1,4 @@
+"""A pytest plugin for building and running Gradescope autograders.
+
+Source: https://github.com/JMU-CS/jmu_pytest_utils/
+"""

jmu_pytest_utils/audit.py

@@ -1,7 +1,8 @@
 """Static analysis of student code.
 
-https://docs.python.org/3/library/ast.html#node-classes
-https://saligrama.io/blog/gradescope-autograder-security/
+References:
+- https://docs.python.org/3/library/ast.html#node-classes
+- https://saligrama.io/blog/gradescope-autograder-security/
 """
 
 import ast

jmu_pytest_utils/common.py

@@ -155,13 +155,13 @@ class redirect_stdin:
     def __init__(self, user_input: str) -> None:
         self._old_input = None
         self._old_stdin = None
-        self.user_input = user_input
+        self._user_input = user_input
 
     def __enter__(self):
         self._old_input = builtins.input
         self._old_stdin = sys.stdin
         builtins.input = _input
-        sys.stdin = io.StringIO(self.user_input)
+        sys.stdin = io.StringIO(self._user_input)
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         builtins.input = self._old_input

jmu_pytest_utils/decorators.py

@@ -12,7 +12,7 @@ def required() -> Callable[[F], F]:
     If a required test fails, the remaining tests are hidden.
 
     Returns:
-        The original function with attribute set.
+        The original function with required attribute set.
     """
     def wrapper(f: F) -> F:
         f.required = True
@@ -27,7 +27,7 @@ def weight(value: int) -> Callable[[F], F]:
         value: The number of points the test is worth.
 
     Returns:
-        The original function with attribute set.
+        The original function with weight attribute set.
     """
     def wrapper(f: F) -> F:
         f.weight = value

jmu_pytest_utils/meta.py

@@ -12,7 +12,7 @@ def get_username(default: str = "username") -> str:
         default: Value to return if metadata not found.
 
     Returns:
-        The student's email address up to the @ symbol.
+        The student's email address before the @ symbol.
     """
     try:
         with open("/autograder/submission_metadata.json") as file:
@@ -66,7 +66,7 @@ def submission_closed() -> bool:
     """Check if the current time is outside the user's submission window.
 
     Returns:
-	The opposite of submission_open() with default arguments.
+        The opposite of `submission_open()` with default arguments.
     """
     return not submission_open()
 

jmu_pytest_utils/plugin.py

@@ -1,7 +1,8 @@
 """Generate the final results.json file for Gradescope.
 
-https://docs.pytest.org/en/stable/reference/reference.html
-https://gradescope-autograders.readthedocs.io/en/latest/specs/
+References:
+- https://docs.pytest.org/en/stable/reference/reference.html
+- https://gradescope-autograders.readthedocs.io/en/latest/specs/
 """
 
 import json