ESMCI/doc-builder

Clean up path in Sphinx complaint messages when using container

Open

#39 opened on Apr 10, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Python (2 forks)auto 404
featuregood first issue

Repository metrics

Stars
 (0 stars)
PR merge metrics
 (PR metrics pending)

Description

Here's an example message when building in the container with a syntax error and --verbose off:

Cleaning documentation build directory...
Done.
Building documentation...
/home/user/mounted_home/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst:168: WARNING: Explicit markup ends without a blank line; unexpected unindent. [docutils]
Documentation build completed, but with problems that must be resolved.
Re-run with --verbose for full output.

The messaging should strip /home/user/mounted_home/, because that path is NOT what the user would need to put in to edit the file. It's a path in the container only.

With verbose on, the original output is probably fine.

Contributor guide

Research direction
Locate the code in doc builder that prints the Sphinx warning messages and modify it to strip the container mount path (e.g., '/home/user/mounted home/') when verbose mode is off.
Tech stack
python
Domain
documentation
Issue type
Bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Python
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75