gh-101100: Fix Py_DEBUG dangling references

[smontanaro]

Per conversation with @AlexWaygood, here is a small proposed fix to a few broken Py_DEBUG links. My suggestion was to reference the _debug-build anchor. Aside from that, all this does so far is suppress dangling Py_DEBUG references in the same paragraphs where the _debug-build anchor is referenced.

• Issue: Fix all Sphinx reference warnings in the documentation #101100

---

📚 Documentation preview 📚: https://cpython-previews--115003.org.readthedocs.build/

[AlexWaygood]

It seems like this PR also includes all the changes from your unrelated other PR:

• gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst #114825

Was that intentional? Perhaps you had your branch for that PR checked out, instead of your main branch, before creating this branch locally? That would mean that this PR branch would "branch off" from that branch, instead of from your main branch :)

[smontanaro]

sigh I just branched from my main. Apologies.

Not sure how to proceed at this point.

[AlexWaygood]

sigh I just branched from my main. Apologies.

Not sure how to proceed at this point.

I fixed things up for you by pushing to your branch (you'll have to git pull locally to update your local clone and make further updates locally 🙂).

I don't work much with the C API, so I don't have strong opinions on the C API docs -- it'd be great if @serhiy-storchaka might be able to take a look at this one

[smontanaro]

Thanks Alex. I'll review and see what else looks like it needs to be changed.

As an aside, I saw a GitHub Actions warning which was new to me:

Is there maybe a parsing problem in whatever tool is involved in that particular GitHub action?

[smontanaro]

Oh, maybe it's complaining about the section below the message, not above it.

[AlexWaygood]

As an aside, I saw a GitHub Actions warning which was new to me:

Is there maybe a parsing problem in whatever tool is involved in that particular GitHub action?

That is warning you about a separate dangling reference later on in the same paragraph (line 820). It's fine to leave that reference warning unsolved in this PR. The reason why you're seeing the warning in the "files changed" tab in this PR is because you have made other changes to that paragraph

[smontanaro]

That is warning you about a separate dangling reference later on in the same paragraph (line 820). It's fine to leave that reference warning unsolved in this PR. The reason why you're seeing the warning in the "files changed" tab in this PR is because you have made other changes to that paragraph

Too late. I will revert it if it's a deal breaker, but I see no reason that it needs to actually be documented in Python's documentation.

[AlexWaygood]

Too late. I will revert it if it's a deal breaker, but I see no reason that it needs to actually be documented in Python's documentation.

I don't think it's a deal-breaker :)

[serhiy-storchaka]

It would be nice to add the Py_DEBUG macro to the index.

Add the .. macro:: Py_DEBUG directive, look what index is generated for it, and add the same index with the .. index:: directive.

[smontanaro]

@serhiy-storchaka I added an explicit :c:macro: PyDEBUG target in intro.rst and referenced it from test.rst. This generates both an anchor for other references and an index entry.

While I was at it, I simplified the text in test.rst. Since it already refers the reader to the debug build details in using/configure.rst, I saw no reason to actually duplicate the configure command example here.

[AlexWaygood]

Looks great!

[miss-islington-app]

Thanks @smontanaro for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app]

Sorry, @smontanaro and @AlexWaygood, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker d0322fdf2c1a7292a43959fe5a572d783b88a1c4 3.11

[bedevere-app]

GH-115135 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

GH-115141 is a backport of this pull request to the 3.11 branch.