readthedocs / readthedocs/ext-theme

Build: add more output details to the build detail page

Open
#171 8 comments 0 reactions 1 assignee View on GitHub

@agjohnson is already working on this.

Since Oct 22, 2025.

Accepted Feature Needed: design decision Status: blocked
Dominant language
HTML
Stars
12
Forks
6
Avg merge
13h 25m
Merged PRs (30d)
1

Description

A secondary discussion that came from https://github.com/readthedocs/readthedocs.org/issues/7005 was around some of the additions lined up for the build detail page, which are roughly tangential to adding a debug flag attribute to the BuildCommand model. These additions would aim to increase the user's understanding of the commands and command steps. There are other additions for the build detail page, but just to focus on improvements to the command listing and/or debug output view:

  • Show the step that the command executed under
  • Show more debug level commands
  • Show command descriptions for some commands

The next step is to experiment more with the display here. All of these changes could negatively affect the build command list, so I'll want to go through a few ideas before settling on what works best here.

A few problems we're solving here:

  • We aren't surfacing where in the build process the command is executed, which would make build.jobs easier to follow and understand
  • We execute commands that aren't clear, for example the cat commands might not make sense if the user isn't familiar with POSIX shells. An annotation or description would help explain what is happening to the user.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.