readthedocs.org (Agent Skills)

# AI Instructions for Read the Docs

This file lives in the `common` repo,
and is copied to each produciton repo.
Agents don't work with symlinks or submodules,
so this is best for now.

## Project Overview

Read the Docs is a documentation hosting platform that builds and hosts documentation for open source projects.
It supports multiple documentation tools (Sphinx, MkDocs, etc.) and automatically builds documentation from Git repositories.

**Technology Stack:**
- Python 3.x
- Django web framework
- Docker and Docker Compose for development
- PostgreSQL database
- Elasticsearch for search
- Redis for caching and Celery for background tasks

## Commits

* Use short descriptive commit messages
* Only provide simple context, and don't be overly verbose
* Always run `pre-commit run --files <changed files>` before committing to ensure code passes all checks

## Pull Requests

* Make the PR description maximum useful for humans, context first and most important.
* Always open pull requests as drafts
* Put a footer note that this was generated by the AI agent in use
* Use feature branches for all changes
* Don't include a "Changes" section, since the PR content is self-explanatory
* Don't include Test Plan unless absolutely necessary.
* Link related issues in the PR description, if there are any in the chat context
* Prefix pull request titles, example `Api:`, `Builds:`, or `Docs:`.

## Package Management

- Always use `uv` for Python package management and virtual environment operations
- Use `uv pip install` instead of `pip install`
- Use `uv run` to execute Python scripts in the virtual environment

## Docs

* Follow the style guide at https://github.com/readthedocs/readthedocs.org/blob/main/docs/dev/style-guide.rst.
* Always use the marketing name used in the public-facing docs, and not the internal code names referenced in code.
* The ``user`` directory is public docs, and ``dev`` is dev-focused. Most of what we do is focus on the user-facing docs.

## Website copy

- Direct, second-person voice. No jargon. Less is more.
- Focus on user benefit, not abstract positioning.
- Don't repeat facts within a section; use standard terminology (e.g. "files changed", "pull request").

## Testing

- Use `pytest` as the testing framework
- Use the `assert foo == bar` style for assertions
- Write succinct, focused tests that test one thing at a time
- Use descriptive test names that explain what is being tested
- Place tests in appropriate test files following the project structure
- Always keep the test db with ``pytest --reuse-db`` to speed up test runs

### Running tests locally

Tests do **not** require Docker — they run via `tox` with SQLite and `readthedocs.settings.test`.
Docker Compose is only for the development server.

```bash
# Validate migrations (run after any migration change)
tox -e migrations

# Run linting and formatting checks
tox -e pre-commit

# Run the main test suite (search, proxito, and embed_api tests are excluded by default)
tox -e py312 -- --nomigrations

# Run tests matching a keyword (faster) — use -k because --pyargs readthedocs is hardcoded
tox -e py312 -- -k "<keyword>" --reuse-db --nomigrations

# Run only search tests (requires Elasticsearch sidecar in CI, skip locally unless available)
tox -e search
```

### Migration validation

Always run `tox -e migrations` after adding or modifying migration files. This runs
`manage.py makemigrations --check --dry-run` and catches missing or inconsistent migrations
before they cause `IntegrityError` failures at deploy time.

## Code Quality

- Follow PEP 8 style guidelines
- Use Django conventions and best practices
- Use type hints for function signatures
- Write clear, concise docstrings for public functions and classes
- Run linters and formatters using `tox -e pre-commit` before committing code

## Front-end

- Most templates/css/js are in a separate repository (https://github.com/readthedocs/ext-theme/).

## Security

- Follow Django security best practices
- Be aware of OWASP top 10 vulnerabilities
- Use Django's built-in security features (CSRF, XSS protection, etc.)