Skip to content

Commit 43c8e2a

Browse files
JacobCoffeeJacobCoffee
authored
Readme updates (#2900)
1 parent 1b9afc1 commit 43c8e2a

7 files changed

Lines changed: 2368 additions & 57 deletions

File tree

‎Makefile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,5 +64,27 @@ test: .state/db-initialized ## Run test suite
6464

6565
ci: lint fmt test ## Run lint, fmt, then tests
6666

67+
# =============================================================================
68+
# Documentation
69+
# =============================================================================
70+
71+
##@ Documentation
72+
73+
docs: docs-clean ## Build documentation
74+
@echo "=> Building documentation"
75+
@uv sync --group docs
76+
@uv run sphinx-build -M html docs/source docs/_build/ -E -a -j auto --keep-going
77+
78+
docs-serve: docs-clean ## Serve documentation with live reload
79+
@echo "=> Serving documentation"
80+
@uv sync --group docs
81+
@uv run sphinx-autobuild docs/source docs/_build/ -j auto --port 0
82+
83+
docs-clean: ## Clean built documentation
84+
@echo "=> Cleaning documentation build assets"
85+
@rm -rf docs/_build
86+
@echo "=> Removed existing documentation build assets"
87+
6788
.PHONY: help serve migrations migrate manage shell docker_shell clean
6889
.PHONY: lint fmt test ci
90+
.PHONY: docs docs-serve docs-clean

‎README.md‎

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,37 @@
33
[![CI](https://github.com/python/pythondotorg/actions/workflows/ci.yml/badge.svg)](https://github.com/python/pythondotorg/actions/workflows/ci.yml)
44
[![Documentation Status](https://readthedocs.org/projects/pythondotorg/badge/?version=latest)](https://pythondotorg.readthedocs.io/?badge=latest)
55

6-
### General information
7-
8-
This is the repository and issue tracker for [python.org](https://www.python.org).
6+
The codebase behind [python.org](https://www.python.org). Built with Django, PostgreSQL, Redis, and Celery.
97

108
> [!NOTE]
11-
> The repository for CPython itself is at https://github.com/python/cpython, and the
12-
> issue tracker is at https://github.com/python/cpython/issues/.
13-
>
9+
> The repository for CPython itself is at https://github.com/python/cpython, and the
10+
> issue tracker is at https://github.com/python/cpython/issues/.
11+
>
1412
> Similarly, issues related to [Python's documentation](https://docs.python.org) can be filed in
1513
> https://github.com/python/cpython/issues/.
1614
15+
### Quick start
16+
17+
```bash
18+
make serve
19+
```
20+
21+
Then visit http://localhost:8000. See the [full setup docs](https://pythondotorg.readthedocs.io/en/latest/install.html) for prerequisites.
22+
1723
### Contributing
1824

19-
* Source code: https://github.com/python/pythondotorg
20-
* Issue tracker: https://github.com/python/pythondotorg/issues
21-
* Documentation: https://pythondotorg.readthedocs.io/
22-
* License: Apache License
25+
Fork the repo, create a branch, and open a pull request. Before submitting:
26+
27+
- Run `make test` and make sure the suite passes
28+
- Run `make lint` and `make fmt`
29+
- Write tests for any new or changed code
30+
- Check for missing migrations with `make migrations`
31+
32+
CI runs on every PR — it checks for ungenerated migrations and enforces a 75%
33+
test coverage minimum. PRs that fail CI won't be merged.
34+
35+
See the full [contributing guide](https://pythondotorg.readthedocs.io/en/latest/contributing.html) for details.
36+
37+
### License
38+
39+
Apache License

‎docs/source/commands.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,26 @@ Management Commands
88
create_initial_data
99
-------------------
1010

11-
This command creates initial data for the app using factories.
11+
.. program:: manage.py create_initial_data
12+
13+
This command creates initial data for the app using factories.
1214
You can run it like::
1315

1416
$ ./manage.py create_initial_data
1517

16-
If you want to remove all existing data in the database before creating
18+
If you want to remove all existing data in the database before creating
1719
new one, specify :option:`--flush` option::
1820

1921
$ ./manage.py create_initial_data --flush
2022

21-
If you want to specify any label to create any app specific data,
23+
If you want to specify any label to create any app specific data,
2224
specify :option:`--app-label` option::
2325

2426
$ ./manage.py create_initial_data --app-label jobs
2527

2628
Command-line options
2729
^^^^^^^^^^^^^^^^^^^^
2830

29-
.. program:: manage.py create_initial_data
30-
3131
.. option:: --flush
3232

3333
Remove existing data in the database before creating new data.

‎docs/source/contributing.rst‎

Lines changed: 50 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,63 @@ Contributing
44
Bugs
55
----
66

7-
All source and content bugs for python.org should be filed as issues on the
8-
GitHub_. Please be sure to look at the existing issues to see if someone has
9-
already submitted it.
7+
File bugs as issues on GitHub_. Check existing issues first to avoid
8+
duplicates.
109

1110
Code
1211
----
1312

14-
The source for python.org is open and licensed under the `Apache 2 license <license_>`_.
15-
To contribute to either the code or documentation please fork the pythondotorg_
16-
repository and submit a pull request.
13+
The source is licensed under the `Apache 2 license <license_>`_. Fork the
14+
pythondotorg_ repository, create a branch, and open a pull request.
1715

18-
See :doc:`install` for setup your development environment.
16+
See :doc:`install` to set up your development environment.
1917

20-
While all contributions are welcome and valuable it will be easier for the
21-
maintainers if you follow good coding practices such as:
18+
Before submitting a PR
19+
~~~~~~~~~~~~~~~~~~~~~~
2220

23-
- Write readable code following :pep:`8` guidelines
24-
- Write tests for the code you are adding or changing
25-
- Submit focused pull requests that address a single smaller issue whenever
26-
possible vs a large pull request that touches many parts of the system
27-
- Submit descriptive information with your pull request as to the reason and
28-
methods behind your change
21+
1. Run the test suite and make sure it passes:
22+
23+
.. code-block:: bash
24+
25+
make test
26+
27+
2. Run the linter and formatter:
28+
29+
.. code-block:: bash
30+
31+
make lint
32+
make fmt
33+
34+
3. If you changed models, check for missing migrations:
35+
36+
.. code-block:: bash
37+
38+
make migrations
39+
40+
4. Write tests for any new or changed code.
41+
42+
5. Keep pull requests focused — one issue or feature per PR is easier to
43+
review than a large PR that touches many parts of the system.
44+
45+
6. Include a clear description of what your PR does and why.
46+
47+
CI checks
48+
~~~~~~~~~
49+
50+
GitHub Actions runs on every push and pull request. It will:
51+
52+
- Check for ungenerated migrations (``makemigrations --check --dry-run``)
53+
- Run the full test suite
54+
- Enforce a **75% minimum test coverage** threshold
55+
56+
PRs that fail CI won't be merged.
57+
58+
Code style
59+
~~~~~~~~~~
60+
61+
- Follow :pep:`8`
62+
- Use ``make lint`` (ruff) to catch issues and ``make fmt`` (ruff) to
63+
auto-format
2964

3065
.. _GitHub: https://github.com/python/pythondotorg/issues
3166
.. _license: https://github.com/python/pythondotorg/blob/main/LICENSE

‎docs/source/index.rst‎

Lines changed: 80 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,93 @@
1-
Welcome to Python.org Website's documentation!
2-
==============================================
1+
python.org
2+
==========
33

4-
Documentation for the code behind python.org_.
4+
.. image:: https://github.com/python/pythondotorg/actions/workflows/ci.yml/badge.svg
5+
:target: https://github.com/python/pythondotorg/actions/workflows/ci.yml
56

6-
General information
7-
-------------------
7+
The codebase behind `python.org <https://www.python.org>`_. It's a Django 5.2
8+
application backed by PostgreSQL, Redis, and Celery, with Elasticsearch
9+
powering site search via Haystack.
810

9-
:Source code: https://github.com/python/pythondotorg
10-
:Issue tracker: https://github.com/python/pythondotorg/issues
11-
:Production configuration: https://github.com/python/psf-salt
12-
:GitHub Actions:
13-
.. image:: https://github.com/python/pythondotorg/actions/workflows/ci.yml/badge.svg
14-
:target: https://github.com/python/pythondotorg/actions/workflows/ci.yml
15-
:License: Apache License
11+
Quick start
12+
-----------
13+
14+
.. code-block:: bash
15+
16+
make serve
17+
18+
Then visit http://localhost:8000. See :doc:`install` for prerequisites and
19+
full setup instructions.
20+
21+
Make targets
22+
------------
23+
24+
:``serve``: Start the full stack (Postgres, Redis, web, worker, static).
25+
:``test``: Run the test suite.
26+
:``migrations``: Generate migrations from model changes.
27+
:``migrate``: Apply pending migrations.
28+
:``manage <cmd>``: Run any Django management command.
29+
:``shell``: Open the Django interactive shell.
30+
:``docker_shell``: Open a bash session inside the web container.
31+
:``clean``: Tear down containers and reset state.
32+
:``lint``: Run the ruff linter with ``--fix``.
33+
:``fmt``: Run the ruff formatter.
34+
:``ci``: Run lint, fmt, then tests in sequence.
35+
36+
Apps at a glance
37+
----------------
38+
39+
**Content & CMS**
40+
``pages``, ``blogs``, ``boxes``, ``codesamples``, ``successstories``,
41+
``minutes``, ``banners``
42+
43+
**Community**
44+
``events``, ``jobs``, ``community``, ``companies``, ``work_groups``
45+
46+
**Core**
47+
``downloads``, ``sponsors``, ``nominations``, ``users``, ``mailing``
48+
49+
**Base**
50+
``cms`` — shared model mixins (``ContentManageable``, ``NameSlugModel``,
51+
etc.) used across most apps.
52+
53+
Docker services
54+
---------------
1655

17-
Contents:
56+
The ``docker-compose.yml`` defines five services:
57+
58+
- **postgres** — PostgreSQL 15.3 database.
59+
- **redis** — Redis 7 for caching and Celery broker.
60+
- **web** — Django dev server on port 8000.
61+
- **worker** — Celery worker with beat scheduler (``django-celery-beat``).
62+
- **static** — SCSS compilation and static asset pipeline.
63+
64+
Testing & CI
65+
------------
66+
67+
Run the full suite:
68+
69+
.. code-block:: bash
70+
71+
make test
72+
73+
Run tests for a single app:
74+
75+
.. code-block:: bash
76+
77+
make manage test events
78+
79+
CI (GitHub Actions) enforces a 75% coverage minimum and checks for missing
80+
migrations. See :doc:`contributing` for PR expectations.
1881

1982
.. toctree::
2083
:maxdepth: 2
21-
:glob:
84+
:hidden:
2285

2386
install.md
2487
contributing
2588
administration
2689
commands
2790

28-
Indices and tables
29-
==================
30-
31-
* :ref:`genindex`
32-
33-
.. _python.org: https://www.python.org
91+
:Source code: https://github.com/python/pythondotorg
92+
:Issue tracker: https://github.com/python/pythondotorg/issues
93+
:License: Apache License

‎pyproject.toml‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,15 @@ dependencies = [
5959
]
6060

6161
[project.optional-dependencies]
62+
prod = [
63+
"gunicorn==23.0.0",
64+
"sentry-sdk[django]==2.40.0",
65+
"Whitenoise==6.11.0",
66+
"django-storages==1.14.4",
67+
"boto3==1.26.165",
68+
]
69+
70+
[dependency-groups]
6271
dev = [
6372
"factory-boy==3.3.1",
6473
"Faker==0.8.1",
@@ -72,16 +81,10 @@ dev = [
7281
]
7382
docs = [
7483
"sphinx",
84+
"sphinx-autobuild",
7585
"myst-parser",
7686
"furo",
7787
]
78-
prod = [
79-
"gunicorn==23.0.0",
80-
"sentry-sdk[django]==2.40.0",
81-
"Whitenoise==6.11.0",
82-
"django-storages==1.14.4",
83-
"boto3==1.26.165",
84-
]
8588

8689
[tool.coverage.run]
8790
branch = true
@@ -175,3 +178,4 @@ known-first-party = [
175178

176179
[tool.ruff.format]
177180
quote-style = "double"
181+

0 commit comments

Comments
 (0)