Nightly CI builds failing - Link Changes

[dylannelson]

Closes #1638

Overview

We noticed builds failing, and it may be due to a link check issue. Stackoverflow is rejecting bots to check the link so it may need to be changed, moved, or removed

Changes:

1. Added 3 Links to the ignore list as they returned 403 errors (bot detection from cloudflare) with no ways around for now
2. Reformatted links on Citation page. Link check tried to look at relative links, and resolve them as web links. Changing them to references (local links) does not make them need to be checked
3. An anchor is needed for to direct the references. Updated the API pages to account for this

PR Checklist

General

• An issue is created and linked
• Added appropriate labels (if your uxarray repo permissions allow it)
• Filled out Overview and Expected Usage (if applicable) sections

Testing & Benchmarking

• [N/A] Adequate tests are created if there is new functionality
• [N/A] Tests are not too basic (such as simply calling a function and nothing else)
• [N/A] Tests cover all major paths in your new functions
• [N/A] If this PR could affect performance, ran ASV benchmarks and confirmed they show expected behavior (add a new benchmark if necessary)

Documentation

• [N/A] Docstrings have been added to all new functions
• [N/A] Docstrings have been updated with any function changes
• [N/A] User (public) functions have been added to docs/api.rst
• [N/A] Internal (private) function names start with an underscore (_)

Examples

• [N/A] All notebook examples cleared the output of all cells before committing
• [N/A] New notebook examples added to appropriate folder (gallery: docs/examples/; guide: docs/user-guide/; quickstart: docs/getting-started/)
• [N/A] New notebook examples referenced in appropriate .rst file (gallery: docs/gallery.rst; guide: docs/userguide.rst; quickstart: docs/quickstart.rst)
• [N/A] New notebook gallery examples added entry in docs/gallery.yml with appropriate thumbnail photo in docs/_static/thumbnails/

AI Disclosure

AI Usage: Claude Code

• I take responsibility for all AI-generated content in my PR.
• I have tested all AI-generated content in my PR.

[dylannelson]

( contributing: line 117) broken https://stackoverflow.com/questions - 403 Client Error: Forbidden for url: https://stackoverflow.com/questions
Still failed after the link was changed to the redirect, so it seems we have to add it to the ignore list

[dylannelson]

Still failed: https://github.com/UXARRAY/uxarray/actions/runs/31812018032/job/94804672219
even adding all 3 links to the ignore list, and making zero 403's appear in the logs still leads to the test failing. Parsed the thousand lines through claude and it suggests this is the cause:

(citations-for-algorithms: line 77)  broken  api.html#descriptors
(citations-for-algorithms: line 84)  broken  api.html#zonal-average
(citations-for-algorithms: line 87)  broken  api.html#intersections
(citations-for-algorithms: line 94)  broken  api.html#arcs
(citations-for-algorithms: line 107) broken  api.html#compensated-arithmetic

[dylannelson]

Full CI run seems to be working now after the changes to 403 and reformatting links on the citation page:
https://github.com/UXARRAY/uxarray/actions/runs/31814480201

We had to do some reformatting to links on the new citation page

• The old links didn't work because they pointed straight at a built page file (api.html#descriptors), and our automatic link checker can't confirm those exist — so it flagged them as broken.
• The new links look like a normal Sphinx reference (:ref:), the same style the rest of our docs already use.
• We changed the API page to add a short label above each linked section, so the new references have something to point at.

Example — the link on the citations page:

Old:  `Descriptors <api.html#descriptors>`__

New:  :ref:`Descriptors <descriptors>`

And the matching label we added in api.rst:

.. _descriptors:

Descriptors
~~~~~~~~~~~

A few valid links (Stack Overflow, SIAM DOIs) were added to linkcheck_ignore because they block the checker with a 403 even though they work in a browser. We tested to see if we can even get these links to show normally when using browser spoofing, and that didn't work either. So no way around 403 for now

[erogluorhan]

Thanks for the fix!

[Sevans711]

All looks good to me! Let's merge to main.

Flagging a related issue I just opened: #1676. My idea is that we might solve two problems at once by adding a run-link-check label which works similarly to the run-benchmark label, as way to opt-in to link-check for a given PR. That would make it easier to debug things like this in the future (no need to find the "run jobs" button separately). But, probably more importantly, it would also reduce the chances for docs-editing PRs like #1635 to cause link-check to fail on main without ever realizing link-check might be a problem.