The HTML page was generated, but “See the packing section” does not link to a real section. Build with warnings treated as failures and inspect the specific unresolved-reference message before delivering the output. The existence of index.html is not the acceptance check.
Use a fictional handoff guide with a named Packing section. The overview should link to that section, which says “Retain the source record with the package.” The fixture contains no application endpoint or external documentation target; its reference should resolve inside the documentation project.
Open the complete example · Download the full HTML source
Name the target before linking to it
In reStructuredText, a small section and explicit label can be:
.. _packing:
Packing
========
Retain the source record with the package.
Elsewhere in the guide, use the reference role:
See :ref:`packing` before sending the package.
Keep the label and its use in the maintained source. Correcting only the generated anchor would leave the next build with the same unresolved source reference.
Run the HTML builder with the chosen failure policy
The Sphinx build-command reference describes source and output directories, builder selection, nitpicky mode, and warning handling. The supplied reproduction pins Sphinx 8.1.3 and retains its matching command documentation with the execution record.
python -m sphinx -n -W -b html source build-good
The surrounding project needs its conf.py and source documents. -n enables nitpicky checks, and -W makes warnings affect build success. Inspect the actual exit code and warning text for the release you use; do not infer success from a page that was written before the command finished.
Prove that the check catches the wrong target
In an isolated copy, change the source reference to missing-packing while keeping the real label packing. Build that copy into a different destination. The intended acceptance test is a failed build with an unresolved-target warning that identifies the missing name.
The broken fixture must fail for the reason you introduced. A missing theme or configuration error is a different failure and does not establish that cross-reference checking worked. Keep the complete log so another person can distinguish those causes.
Restore the reference to packing, build the corrected source into the good destination, and follow the generated link. Require a real destination element and the expected Packing heading. The exit result and the working anchor establish different parts of the handoff.
The existing API documentation guide addresses the content of operation and error examples. This Sphinx task concerns generated cross-references; passing it does not validate the underlying technical instructions or API behavior.
Deliver the accepted build and its source
Keep source, configuration, version, and the successful build log together. Retain the failed reproduction separately as evidence that the check was meaningful. Package the generated resource folder with the HTML when that is the chosen delivery format.
When a reviewer changes a section name or target, update the source reference and rerun the same acceptance command. Finish the handoff only after both the corrected build and the link destination agree with the maintained guide.
Download the maintained source and actual output archive. This archive retains the supplied fixture and the original generated files beside the reading copy.