Readme updates

Makefile

@@ -64,5 +64,27 @@ test: .state/db-initialized ## Run test suite
 
 ci: lint fmt test ## Run lint, fmt, then tests
 
+# =============================================================================
+# Documentation
+# =============================================================================
+
+##@ Documentation
+
+docs: docs-clean ## Build documentation
+	@echo "=> Building documentation"
+	@uv sync --group docs
+	@uv run sphinx-build -M html docs/source docs/_build/ -E -a -j auto --keep-going
+
+docs-serve: docs-clean ## Serve documentation with live reload
+	@echo "=> Serving documentation"
+	@uv sync --group docs
+	@uv run sphinx-autobuild docs/source docs/_build/ -j auto --port 0
+
+docs-clean: ## Clean built documentation
+	@echo "=> Cleaning documentation build assets"
+	@rm -rf docs/_build
+	@echo "=> Removed existing documentation build assets"
+
 .PHONY: help serve migrations migrate manage shell docker_shell clean
 .PHONY: lint fmt test ci
+.PHONY: docs docs-serve docs-clean

README.md

@@ -3,20 +3,37 @@
 [![CI](https://github.com/python/pythondotorg/actions/workflows/ci.yml/badge.svg)](https://github.com/python/pythondotorg/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/pythondotorg/badge/?version=latest)](https://pythondotorg.readthedocs.io/?badge=latest)
 
-### General information
-
-This is the repository and issue tracker for [python.org](https://www.python.org). 
+The codebase behind [python.org](https://www.python.org). Built with Django, PostgreSQL, Redis, and Celery.
 
 > [!NOTE]
-> The repository for CPython itself is at https://github.com/python/cpython, and the 
-> issue tracker is at https://github.com/python/cpython/issues/. 
-> 
+> The repository for CPython itself is at https://github.com/python/cpython, and the
+> issue tracker is at https://github.com/python/cpython/issues/.
+>
 > Similarly, issues related to [Python's documentation](https://docs.python.org) can be filed in
 > https://github.com/python/cpython/issues/.
 
+### Quick start
+
+```bash
+make serve
+```
+
+Then visit http://localhost:8000. See the [full setup docs](https://pythondotorg.readthedocs.io/en/latest/install.html) for prerequisites.
+
 ### Contributing
 
-* Source code: https://github.com/python/pythondotorg
-* Issue tracker: https://github.com/python/pythondotorg/issues
-* Documentation: https://pythondotorg.readthedocs.io/
-* License: Apache License
+Fork the repo, create a branch, and open a pull request. Before submitting:
+
+- Run `make test` and make sure the suite passes
+- Run `make lint` and `make fmt`
+- Write tests for any new or changed code
+- Check for missing migrations with `make migrations`
+
+CI runs on every PR — it checks for ungenerated migrations and enforces a 75%
+test coverage minimum. PRs that fail CI won't be merged.
+
+See the full [contributing guide](https://pythondotorg.readthedocs.io/en/latest/contributing.html) for details.
+
+### License
+
+Apache License

docs/source/commands.rst

@@ -8,26 +8,26 @@ Management Commands
 create_initial_data
 -------------------
 
-This command creates initial data for the app using factories. 
+.. program:: manage.py create_initial_data
+
+This command creates initial data for the app using factories.
 You can run it like::
 
     $ ./manage.py create_initial_data
 
-If you want to remove all existing data in the database before creating 
+If you want to remove all existing data in the database before creating
 new one, specify :option:`--flush` option::
 
     $ ./manage.py create_initial_data --flush
 
-If you want to specify any label to create any app specific data, 
+If you want to specify any label to create any app specific data,
 specify :option:`--app-label` option::
 
     $ ./manage.py create_initial_data --app-label jobs
 
 Command-line options
 ^^^^^^^^^^^^^^^^^^^^
 
-.. program:: manage.py create_initial_data
-
 .. option:: --flush
 
    Remove existing data in the database before creating new data.

docs/source/contributing.rst

@@ -4,28 +4,63 @@ Contributing
 Bugs
 ----
 
-All source and content bugs for python.org should be filed as issues on the
-GitHub_.  Please be sure to look at the existing issues to see if someone has
-already submitted it.
+File bugs as issues on GitHub_. Check existing issues first to avoid
+duplicates.
 
 Code
 ----
 
-The source for python.org is open and licensed under the `Apache 2 license <license_>`_.
-To contribute to either the code or documentation please fork the pythondotorg_
-repository and submit a pull request.
+The source is licensed under the `Apache 2 license <license_>`_. Fork the
+pythondotorg_ repository, create a branch, and open a pull request.
 
-See :doc:`install` for setup your development environment.
+See :doc:`install` to set up your development environment.
 
-While all contributions are welcome and valuable it will be easier for the
-maintainers if you follow good coding practices such as:
+Before submitting a PR
+~~~~~~~~~~~~~~~~~~~~~~
 
-- Write readable code following :pep:`8` guidelines
-- Write tests for the code you are adding or changing
-- Submit focused pull requests that address a single smaller issue whenever
-  possible vs a large pull request that touches many parts of the system
-- Submit descriptive information with your pull request as to the reason and
-  methods behind your change
+1. Run the test suite and make sure it passes:
+
+   .. code-block:: bash
+
+      make test
+
+2. Run the linter and formatter:
+
+   .. code-block:: bash
+
+      make lint
+      make fmt
+
+3. If you changed models, check for missing migrations:
+
+   .. code-block:: bash
+
+      make migrations
+
+4. Write tests for any new or changed code.
+
+5. Keep pull requests focused — one issue or feature per PR is easier to
+   review than a large PR that touches many parts of the system.
+
+6. Include a clear description of what your PR does and why.
+
+CI checks
+~~~~~~~~~
+
+GitHub Actions runs on every push and pull request. It will:
+
+- Check for ungenerated migrations (``makemigrations --check --dry-run``)
+- Run the full test suite
+- Enforce a **75% minimum test coverage** threshold
+
+PRs that fail CI won't be merged.
+
+Code style
+~~~~~~~~~~
+
+- Follow :pep:`8`
+- Use ``make lint`` (ruff) to catch issues and ``make fmt`` (ruff) to
+  auto-format
 
 .. _GitHub: https://github.com/python/pythondotorg/issues
 .. _license: https://github.com/python/pythondotorg/blob/main/LICENSE

docs/source/index.rst

@@ -1,33 +1,93 @@
-Welcome to Python.org Website's documentation!
-==============================================
+python.org
+==========
 
-Documentation for the code behind python.org_.
+.. image:: https://github.com/python/pythondotorg/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/python/pythondotorg/actions/workflows/ci.yml
 
-General information
--------------------
+The codebase behind `python.org <https://www.python.org>`_. It's a Django 5.2
+application backed by PostgreSQL, Redis, and Celery, with Elasticsearch
+powering site search via Haystack.
 
-:Source code: https://github.com/python/pythondotorg
-:Issue tracker: https://github.com/python/pythondotorg/issues
-:Production configuration: https://github.com/python/psf-salt
-:GitHub Actions:
-  .. image:: https://github.com/python/pythondotorg/actions/workflows/ci.yml/badge.svg
-       :target: https://github.com/python/pythondotorg/actions/workflows/ci.yml
-:License: Apache License
+Quick start
+-----------
+
+.. code-block:: bash
+
+   make serve
+
+Then visit http://localhost:8000. See :doc:`install` for prerequisites and
+full setup instructions.
+
+Make targets
+------------
+
+:``serve``: Start the full stack (Postgres, Redis, web, worker, static).
+:``test``: Run the test suite.
+:``migrations``: Generate migrations from model changes.
+:``migrate``: Apply pending migrations.
+:``manage <cmd>``: Run any Django management command.
+:``shell``: Open the Django interactive shell.
+:``docker_shell``: Open a bash session inside the web container.
+:``clean``: Tear down containers and reset state.
+:``lint``: Run the ruff linter with ``--fix``.
+:``fmt``: Run the ruff formatter.
+:``ci``: Run lint, fmt, then tests in sequence.
+
+Apps at a glance
+----------------
+
+**Content & CMS**
+   ``pages``, ``blogs``, ``boxes``, ``codesamples``, ``successstories``,
+   ``minutes``, ``banners``
+
+**Community**
+   ``events``, ``jobs``, ``community``, ``companies``, ``work_groups``
+
+**Core**
+   ``downloads``, ``sponsors``, ``nominations``, ``users``, ``mailing``
+
+**Base**
+   ``cms`` — shared model mixins (``ContentManageable``, ``NameSlugModel``,
+   etc.) used across most apps.
+
+Docker services
+---------------
 
-Contents:
+The ``docker-compose.yml`` defines five services:
+
+- **postgres** — PostgreSQL 15.3 database.
+- **redis** — Redis 7 for caching and Celery broker.
+- **web** — Django dev server on port 8000.
+- **worker** — Celery worker with beat scheduler (``django-celery-beat``).
+- **static** — SCSS compilation and static asset pipeline.
+
+Testing & CI
+------------
+
+Run the full suite:
+
+.. code-block:: bash
+
+   make test
+
+Run tests for a single app:
+
+.. code-block:: bash
+
+   make manage test events
+
+CI (GitHub Actions) enforces a 75% coverage minimum and checks for missing
+migrations. See :doc:`contributing` for PR expectations.
 
 .. toctree::
    :maxdepth: 2
-   :glob:
+   :hidden:
 
    install.md
    contributing
    administration
    commands
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-
-.. _python.org: https://www.python.org
+:Source code: https://github.com/python/pythondotorg
+:Issue tracker: https://github.com/python/pythondotorg/issues
+:License: Apache License

pyproject.toml

@@ -59,6 +59,15 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+prod = [
+    "gunicorn==23.0.0",
+    "sentry-sdk[django]==2.40.0",
+    "Whitenoise==6.11.0",
+    "django-storages==1.14.4",
+    "boto3==1.26.165",
+]
+
+[dependency-groups]
 dev = [
     "factory-boy==3.3.1",
     "Faker==0.8.1",
@@ -72,16 +81,10 @@ dev = [
 ]
 docs = [
     "sphinx",
+    "sphinx-autobuild",
     "myst-parser",
     "furo",
 ]
-prod = [
-    "gunicorn==23.0.0",
-    "sentry-sdk[django]==2.40.0",
-    "Whitenoise==6.11.0",
-    "django-storages==1.14.4",
-    "boto3==1.26.165",
-]
 
 [tool.coverage.run]
 branch = true
@@ -175,3 +178,4 @@ known-first-party = [
 
 [tool.ruff.format]
 quote-style = "double"
+