AGENTS.md

Copilot Instructions for Read the Docs

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

Pull Requests

• Put a footer note that this was generated by Copilot
• Use feature branches for all changes
• Don't include a "Changes" section, since the PR content is self-explanatory
• Link related issues in the PR description, if there are any in the chat context
• Prefix pull request titles with the part of the system being worked on, for 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.

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

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.)