1654923 - Link is broken when file is edited, fixed when "mach doc" restarted

Status: RESOLVED DUPLICATE of bug 1557020

(Developer Infrastructure :: Source Documentation, defect)

Description

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Video showing steps to reproduce link that breaks if file changes, even if change is reverted

I have a link from build/docs/telemetry.rst to python/mach/docs/telemetry.rst (this file not yet in-tree at the time of posting this bug) that looks like this:

In addition to the existing build-specific telemetry, Mozbuild is also reporting data ... via :ref:`mach_telemetry`.

When I first start ./mach doc, the generated documentation properly links from Build Telemetry to Mach Telemetry. However, when I edit the build/docs/telemetry.rst file (even a trivial change, like adding a space elsewhere), the link becomes broken. Reverting my change doesn't resolve the issue - the only way for the link to work again is to restart ./mach doc. 🤔

(Here's a little screenrecording showing the issue)

Comment 1

[Andrew Halberstadt [:ahal]]

This is a known issue and I think there's a bug on file (on mobile otherwise I'd find it). Basically what's happening is that when you modify a file we rebuild only the doc tree that contains it as the full build is painfully slow. But due to how the system is set up this clobbers all the other tree's. I recall trying to fix this when I first landed the livereload feature and giving up as it was too hard. I don't remember why though.

Comment 2

[Andrew Halberstadt [:ahal]]

Found the bug, going to duplicate.