Docs update

Author: mfosterw

CONTRIBUTING.rst

@@ -120,8 +120,8 @@ Creating a Webhook
 
 :obj:`democrasite.webiscite` needs `webhooks`_ to find out about events on
 Github. `Create a webhook`_ in your fork of the repository, then generate a
-secret key for your hook and store it in your environment (either through your
-terminal or ``.env`` file) as ``GITHUB_SECRET_KEY``.
+secret key for your hook and store it in ``.envs/.local/.django`` (or your shell) as
+``GITHUB_WEBHOOK_SECRET`` so it matches the secret configured on GitHub.
 
 To test your webhook, follow these `instructions`_. (If you have a preferred
 tool for exposing your local server, feel free to replace smee with it.) If you

README.rst

@@ -74,7 +74,7 @@ following the instructions in the guide.
 Understanding the repository
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Check out ``repo_map.txt`` in the root of the repository for a display of the
+Check out ``repository_map.txt`` in the root of the repository for a display of the
 repository layout and brief explanations for the purpose of each non-obvious file and
 directory.
 
@@ -114,8 +114,8 @@ Setting up your users
   how the site behaves for both kinds of users.
 
 .. _`django-allauth`: https://docs.allauth.org/en/latest/introduction/index.html
-.. _`GitHub`: https://django-allauth.readthedocs.io/en/latest/providers.html#github
-.. _`Google`: https://docs.allauth.org/en/latest/socialaccount/providers/github.html
+.. _`GitHub`: https://docs.allauth.org/en/latest/socialaccount/providers/github.html
+.. _`Google`: https://docs.allauth.org/en/latest/socialaccount/providers/google.html
 
 Linting
 ^^^^^^^

docs/howto.rst

@@ -4,15 +4,18 @@ How To - Project Documentation
 Get Started
 ----------------------------------------------------------------------
 
-Documentation can be written as rst files in `democrasite/docs`.
+Documentation source files live in the ``docs/`` directory at the repository root.
 
 
-To build and serve docs, use the commands::
+To build and serve docs with live reload, start the local stack (including the ``docs``
+service) from the project root::
 
-    docker compose -f docker-compose.docs.yml up
+    just up
 
+The docs container serves Sphinx at http://localhost:9000/ (see ``docker-compose.local.yml``).
 
-Changes to files in `docs` will be picked up and reloaded automatically.
+Changes to files under ``docs/`` and under ``democrasite/`` (watched by sphinx-autobuild)
+will be picked up and reloaded automatically.
 
 `Sphinx <https://www.sphinx-doc.org/>`_ is the tool used to build documentation.
 

docs/webiscite.rst

@@ -27,10 +27,14 @@ 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 :class:`~django_celery_beat.models.PeriodicTask` is
-also scheduled to execute :func:`~democrasite.webiscite.tasks.submit_bill`
-once the voting period ends.
+is created with the information from the pull request. If the pull request is
+still a GitHub draft, the bill stays in ``DRAFT`` status (no voting) until the
+PR is marked ready for review, which publishes it via
+:meth:`~democrasite.webiscite.webhooks.PullRequestHandler.ready_for_review`.
+Otherwise the bill is ``OPEN`` on the homepage. A
+:class:`~django_celery_beat.models.PeriodicTask` is scheduled to execute
+:func:`~democrasite.webiscite.tasks.submit_bill` once the voting period ends
+(enabled when the bill leaves ``DRAFT``).
 
 :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