Add BuildCommand support and missing fields to API v3 Build endpoint

[Copilot]

Summary: Add missing fields to API v3 Build endpoint ✅

All requirements from the issue have been successfully implemented:

• Add commands field to BuildSerializer (BuildCommand support)
• Add docs_url field to BuildSerializer
• Add commit_url field to BuildSerializer
• Add builder field to BuildSerializer (for debugging)
• Support ?expand=config for the config object (verified existing functionality)
• Support ?expand=notifications for notifications expansion
• Add comprehensive tests for the new fields
• Update public REST API documentation (not design docs)

Implementation Details

1. Serializers (readthedocs/api/v3/serializers.py)

Added BuildCommandSerializer:

class BuildCommandSerializer(serializers.ModelSerializer):
    """Serializer for BuildCommandResult objects."""
    run_time = serializers.ReadOnlyField()
    
    class Meta:
        model = BuildCommandResult
        fields = ["id", "command", "description", "output", 
                  "exit_code", "start_time", "end_time", "run_time"]

Enhanced BuildSerializer with new fields:

• commands: List of BuildCommandResult objects (many=True)
• docs_url: URL to built documentation via get_docs_url() method
• commit_url: URL to VCS commit via model's get_commit_url()
• builder: Builder hostname for debugging purposes
• Added notifications to expandable_fields for ?expand=notifications support

2. Views (readthedocs/api/v3/views.py)

Updated BuildsViewSet.permit_list_expands to include "notifications" alongside existing "config".

3. Tests (readthedocs/api/v3/tests/)

Test fixtures updated:

• Added BuildCommandResult import to test mixins
• Created sample BuildCommandResult in test setup
• Updated JSON response fixtures with new fields

New test coverage:

• test_projects_builds_detail_has_new_fields(): Validates presence and values of new fields
• test_projects_builds_detail_expand_config(): Tests config expansion
• test_projects_builds_detail_expand_notifications(): Tests notification expansion

4. Documentation (docs/user/api/v3.rst)

Updated public REST API documentation with:

• Example response showing new fields (commands, commit_url, docs_url, builder)
• Field descriptions for all new fields
• Updated expand parameter documentation to include notifications

Code Quality

✅ All Python files pass syntax validation
✅ All JSON fixtures are valid
✅ Implementation follows existing v2 API patterns
✅ Consistent error handling (returns None for missing version)
✅ No trailing whitespace or obvious style issues
✅ Comprehensive docstrings added

API Usage Examples

Get build with new fields:

GET /api/v3/projects/{project}/builds/{build_id}/

Expand config:

GET /api/v3/projects/{project}/builds/{build_id}/?expand=config

Expand notifications:

GET /api/v3/projects/{project}/builds/{build_id}/?expand=notifications

Expand both:

GET /api/v3/projects/{project}/builds/{build_id}/?expand=config,notifications

This implementation addresses all requirements from the issue and brings the v3 Build API to feature parity with v2 while supporting the new dashboard needs.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>API: BuildCommands and missing fields to build v3 API</issue_title>
<issue_description>On the new dashboard, the build detail view is still using the v2 API. I would like to eventually rely on APIv3 on the dashboard, as that is the stronger API. I encountered the following data from the v2 API was not implemented in the V3 API however:

• BuildCommands don't seem to be implemented -- this is the largest blocker
• docs_url
• commit_url
• builder (for debugging only, not super important)

I did find I need the following changes once I can use the APIv3 build enpoint:

• add ?expand=config for the config object

It would help if we could expand the notifications on the build APIv3 call and save the extra polling calls. Without this, that view needs to poll two APIs every two seconds while the build is still active.

For now, I can use the notification API v2 endpoints.</issue_description>

<agent_instructions>Please do this in a minimal way that is focused on looking similar to our existing API. Include tests and docs that build on the existing versions of those files, without creating a new file. </agent_instructions>

Comments on the Issue (you are @copilot in this section)

@humitos Noting for reference that we may also want to add `?expand=notifications` for the APIv3 build endpoint: https://github.com/readthedocs/ext-theme/pull/300#discussion_r1540912107 @agjohnson Pushing this to later, but we should consider fixing up build API v3 for our use high priority and get away from relying on API v2. @agjohnson I'm not sure exactly how to prioritize this at the moment, I was hoping we'd be farther into APIv3 fixes for permissions probably. I'm going to move this to new dashboard features milestone, even though this isn't much of a feature.

• Fixes API: BuildCommands and missing fields to build v3 API #11179

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[read-the-docs-community]

Documentation build overview

📚 dev | 🛠️ Build #30265243 | 📁 Comparing 3021e5a against latest (8c4761a)

🔍 Preview build

No files changed.

[ericholscher]

@copilot Update the public REST API docs, not the design docs.

[Copilot]

@copilot Update the public REST API docs, not the design docs.

Updated the public REST API docs (docs/user/api/v3.rst) instead of the design docs. The changes include:

• Added example response showing the new fields (commands, commit_url, docs_url, builder)
• Added field descriptions for all new fields with details about the commands array structure
• Updated the expand parameter documentation to include notifications

Commit: 3021e5a

[read-the-docs-community]

Documentation build overview

📚 docs | 🛠️ Build #30265244 | 📁 Comparing 3021e5a against latest (8c4761a)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
api/v3.html	📝 modified