Repository: python/peps

Issue:
Don't auto-add inline links to ref section & rm if empty, per #2130
First step to implementing #2130 , as agreed with @gvanrossum and the PEP editor team.

When building, don't add redundant footnotes and references entries for URLs that are already directly linked inline. This avoids an unnecessary, potentially confusing footnote for each link, and taking up additional space in the references section for no real benefit, plus simplifies the build code and should improve build time, especially for Sphinx. Furthermore, if the references section is empty (not including now-invisible link targets), remove it, as we did before (but in a more robust manner). This allows past and future PEPs to still use inline references with targets stored in the references section, while avoiding showing a now-empty references section.

These are both implemented for Sphinx and the legacy builder, and I visually inspected a variety of PEPs with various cases with both builders to ensure the desired results were achieved, and there were no obvious side effects from this change.

Following merging this PR, following the plan outlined in #2130 , I'll proceed with one updating the meta-PEP docs in PEP 0, PEP 1 and PEP 12 to reflect the revised policy of using standard reST links (inline or with separate targets) rather than the references section, and follow that with a PR updating the relative handful of references in the other active meta-PEPs, for consistency.


Discussion:
Hey @JelleZijlstra or others, are there any blockers to merging this? This would make my [PEP 639](https://www.python.org/dev/peps/pep-0639/#references) over _five full pages_ shorter (since it has around 100 links) and it seems we all agree on it, and then I can proceed with Part 2, a PR updating PEP 1 and PEP 12 , etc., to reflect this.

This also unblocks/avoids merge conflicting with @AA-Turner 's important work to implement [PEP 676](https://discuss.python.org/t/pep-639-round-2-improving-license-clarity-with-better-package-metadata/12622/17), which among other things actually opens up a much better approach to addressing your concerns about PEP 639's excessive length, drastically reducing it (on top of cutting down verbosity and specific portions that can be elided, which I'm working on with @pradyunsg ) by moving around two thirds of the PEP text (which is appendices, documentation of rejected ideas and ancillary material) to separate supporting files in the `pep-0639` subdirectory, without loosing it completely.

Thanks!
& gone in [https://python.github.io/peps/pep-0639](https://python.github.io/peps/pep-0639/#copyright)!
Thanks so much @JelleZijlstra , @gvanrossum and @AA-Turner !
Thank *you*! Have you been promoted to PEP editor yet?
Hahaha @gvanrossum , I'm still at "PEP intern" status :laughing: But you never know, maybe someday, given that I sure am a lot better at ~nitpicking~ proofreading, ~rewriting~ copyediting, and ~pedantry~ formatting English technical documents than I am at programming, even in my favorite British-comedy-troupe-themed language created by some Dutch guy...
FYI @AA-Turner , looks like our 5788d8a resulted in my multiple-layers-of-indirection links in PEP 639 resolving to anchors on the page rather than the links themselves with the legacy build system (things work fine with your new build system, and my previous commit also works). Not sure how I missed this in testing, sorry...I must not have carefully checked a range of links on that specific PR on the old build system for the final version of that commit, despite having done so for the previous one. Seems your trust was misplaced after all, @gvanrossum :cry: 

I suspect it has to do with the delayed callback to delete the references section being necessary so that the links get resolved before the section is deleted and their original targets removed. I'll test and confirm and have a followup PR shortly to fix that.
Don’t worry CAM, I’ve done worse. :-)

Resolving patch:
diff --git a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
--- a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
+++ b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
@@ -18,8 +18,8 @@ class PEPFooter(transforms.Transform):
 
     """
 
-    # Uses same priority as docutils.transforms.TargetNotes
-    default_priority = 520
+    # Set low priority so ref targets aren't removed before they are needed
+    default_priority = 999
 
     def apply(self) -> None:
         pep_source_path = Path(self.document["source"])


Test patch: