Fix outdated documentation and incorrect docstrings

- Update docs/webiscite.rst to reflect current architecture: GithubWebhookView
  and PullRequestHandler replace the removed github_hook, process_pull, and
  pr_opened identifiers
- Fix managers.py docstrings: correct parameter names and return descriptions
  for create_from_github on both managers; add missing docstrings to
  get_queryset and annotate_user_vote; add module docstring
- Fix webhooks.py docstrings: update module docstring to class-based view;
  fix _validate_header and _validate_signature return type descriptions
- Add missing module docstring to activitypub/models.py

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mfosterw

democrasite/activitypub/models.py

@@ -1,3 +1,5 @@
+"""Models for the activitypub app."""
+
 from django.contrib.auth import get_user_model
 from django.db import models
 from django.urls import reverse

democrasite/webiscite/managers.py

@@ -1,3 +1,5 @@
+"""Managers for the webiscite app models."""
+
 import json
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -24,16 +26,14 @@
 
 class PullRequestManager[T](models.Manager):
     def create_from_github(self, pr: dict[str, Any]) -> T:
-        """Create a :class:`~democrasite.webiscite.models.PullRequest` and optionally a
-        :class:`~democrasite.webiscite.models.Bill` instance from a GitHub pull request
+        """Create or update a :class:`~democrasite.webiscite.models.PullRequest` from
+        a GitHub pull request payload
 
         Args:
-            pr_args: The parameters for the ``PullRequest``
-            bill_args: The parameters for the ``Bill`` or None
+            pr: The pull request data from the GitHub API
 
         Returns:
-            A tuple containing the new or updated pull request and new bill instance, if
-            applicable
+            The new or updated pull request instance
         """
         pull_request, created = self.update_or_create(
             number=pr["number"],
@@ -54,6 +54,12 @@ def create_from_github(self, pr: dict[str, Any]) -> T:
 
 class BillManager[T](models.Manager):
     def get_queryset(self):
+        """Return a queryset with pull_request pre-fetched and vote percentages added.
+
+        All Bill querysets include ``total_votes``, ``yes_percent``, and
+        ``no_percent``
+        annotations, and are ordered by creation date.
+        """
         return (
             super()
             .get_queryset()
@@ -87,6 +93,16 @@ def get_queryset(self):
     def annotate_user_vote(
         self, user: User, queryset: models.QuerySet["Bill"] | None = None
     ):
+        """Annotate a queryset with the given user's vote on each bill.
+
+        Args:
+            user: The user whose vote to annotate
+            queryset: The queryset to annotate; defaults to ``self.get_queryset()``
+
+        Returns:
+            The queryset annotated with a ``user_vote`` field
+            (``True``/``False``/``None``)
+        """
         if queryset is None:
             queryset = self.get_queryset()
 
@@ -111,13 +127,15 @@ def create_from_github(
         GitHub pull request
 
         Args:
-            pr: The pull request data from the GitHub API
-            diff_text: The text of the diff of the pull request
+            title: The title of the pull request
+            body: The body/description of the pull request
+            author: The user who authored the pull request
+            diff_text: The text of the diff of the pull request, used to determine
+                whether the bill is constitutional
             pull_request: The pull request instance to associate with the bill
 
         Returns:
-            A tuple containing the new or update pull request and new bill instance, if
-            applicable
+            The newly created bill instance
         """
         with self._create_submit_task() as submit_task:
             self._bill: Bill = self.model(

democrasite/webiscite/webhooks.py

@@ -1,6 +1,6 @@
 """Views for processing webhooks.
 
-Each service that sends webhooks should have its own function-based view."""
+Each service that sends webhooks should have its own class-based view."""
 
 import hmac
 import json
@@ -138,10 +138,10 @@ def _validate_header(headers: request.HttpHeaders) -> HttpResponseBadRequest | N
         """Validate the headers of a request from a webhook
 
         Args:
-            headers (dict): The headers from the request to validate
+            headers: The headers from the request to validate
 
         Returns:
-            str: Error message if the headers are invalid, otherwise an empty string
+            A bad request response if required headers are missing, otherwise ``None``
         """
         header_signature = headers.get("x-hub-signature-256")
         if header_signature is None:
@@ -164,11 +164,12 @@ def _validate_signature(
         """Validate the signature of a request from a webhook
 
         Args:
-            header_signature (str): The signature from the request to validate
-            request_body (bytes): The body of the request to validate
+            header_signature: The HMAC signature from the request headers
+            request_body: The raw body of the request to validate
 
         Returns:
-            str: Error message if the signature is invalid, otherwise an empty string
+            An error response if the signature is invalid or uses an unsupported
+            digest, otherwise ``None``
         """
         digest_name, signature = header_signature.split("=")
         if digest_name != "sha256":

docs/webiscite.rst

@@ -15,23 +15,27 @@ Pull Requests
 Pull Request Processing Pipeline
 --------------------------------
 
-When a pull request is created on `GitHub`_, a `webhook`_ makes a request to
-the GitHub :func:`webhook view <democrasite.webiscite.webhooks.github_hook>`.
+When a pull request is created on `GitHub`_, a `webhook`_ makes a POST request
+to the :class:`~democrasite.webiscite.webhooks.GithubWebhookView`, which
+validates the request signature and dispatches to the appropriate handler.
 
-This method parses the data from the request and calls
-:func:`~democrasite.webiscite.tasks.process_pull`
-to handle the request. In the event a pull request was opened or reopened,
-:func:`~democrasite.webiscite.tasks.pr_opened` is called.
+For pull request events, the request is handled by
+:class:`~democrasite.webiscite.webhooks.PullRequestHandler`. When a pull
+request is opened or reopened, its
+:meth:`~democrasite.webiscite.webhooks.PullRequestHandler.opened` method
+creates a :class:`~democrasite.webiscite.models.PullRequest` instance.
 
 If the user who created the pull request has a democrasite account, a new
 :class:`~democrasite.webiscite.models.Bill`
 is created with the information from the pull request and made visible on the
-homepage immediately.
-
-A task to execute :func:`~democrasite.webiscite.tasks.submit_bill`
-is also put in the celery queue to execute once the voting period ends. The
-function verifies that the pull request is open and unedited and then counts
-the votes for and against that Bill.
+homepage immediately. A :class:`~django_celery_beat.models.PeriodicTask` is
+also scheduled to execute :func:`~democrasite.webiscite.tasks.submit_bill`
+once the voting period ends.
+
+:func:`~democrasite.webiscite.tasks.submit_bill` verifies that the pull
+request is still open and that its SHA has not changed since the bill was
+created (i.e. the pull request has not been edited), then counts the votes for
+and against that Bill.
 
 If the votes for the Bill pass the threshold, the pull request is merged into
 the master branch on Github and automatically deployed, officially making it