readthedocs hits GitHub rate limit

[OptimumCode]

After a change made in #1867, we perform a few API calls to collect known test harnesses outside the bowtie repository during bowtie build. Because of that, some documentation preview jobs hit the rate limit. Example:
https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/

Error in case the link does not work anymore

Using Python 3.12.7 environment at: /home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/envs/1913
Resolved 83 packages in [2](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--2).69s
   Building bowtie-json-schema @ file:///home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/checkouts/191[3](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--3)
   Building pygments-github-lexers==0.0.5
Downloading beartype (1.1MiB)
Downloading aiohttp (1.6MiB)
Downloading lxml ([4](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--4).8MiB)
 Downloaded aiohttp
 Downloaded lxml
 Downloaded beartype
      Built pygments-github-lexers==0.0.[5](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--5)
  × Failed to build `bowtie-json-schema @
  │ file:///home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/checkouts/1913`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `hatchling.build.build_wheel` failed (exit status: 1)
      [stderr]
      /home/docs/.cache/uv/builds-v0/.tmp5NRSiZ/lib/python3.12/site-packages/setuptools_scm/git.py:1[6](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--6)7:
      UserWarning:
      "/home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/checkouts/1913"
      is shallow and may cause errors
        warnings.warn(f'"{wd.path}" is shallow and may cause errors')
      neither BUILD_GITHUB_TOKEN nor GITHUB_TOKEN are provided. You can reach
      the GitHub rate limit
      Traceback (most recent call last):
        File "<string>", line 11, in <module>
        File
      "/home/docs/.cache/uv/builds-v0/.tmp5NRSiZ/lib/python3.12/site-packages/hatchling/build.py",
      line 58, in build_wheel
          return os.path.basename(next(builder.build(directory=wheel_directory,
      versions=['standard'])))
      
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File
      "/home/docs/.cache/uv/builds-v0/.tmp5NRSiZ/lib/python3.12/site-packages/hatchling/builders/plugin/interface.py",
      line 14[7](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--7), in build
          build_hook.initialize(version, build_data)
        File
      "/home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/checkouts/1913/hatch_build.py",
      line 42, in initialize
          known = self._known_implementations_from_github(known)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File
      "/home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/checkouts/1913/hatch_build.py",
      line [8](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--8)7, in _known_implementations_from_github
          harnesses = self._collect_harnesses(gh_token)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File
      "/home/docs/checkouts/readthedocs.org/user_builds/bowtie-json-schema/checkouts/1[9](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--9)13/hatch_build.py",
      line [10](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--10)8, in _collect_harnesses
          org = gh.organization("bowtie-json-schema")
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File
      "/home/docs/.cache/uv/builds-v0/.tmp5NRSiZ/lib/python3.[12](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--12)/site-packages/github3/github.py",
      line 1688, in organization
          json = self._json(self._get(url), 200)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File
      "/home/docs/.cache/uv/builds-v0/.tmp5NRSiZ/lib/python3.12/site-packages/github3/models.py",
      line 161, in _json
          raise exceptions.error_for(response)
      github3.exceptions.ForbiddenError: 403 API rate limit exceeded for
      [13](https://app.readthedocs.org/projects/bowtie-json-schema/builds/27634246/#265242963--13).59.193.41. (But here's the good news: Authenticated requests get a
      higher rate limit. Check out the documentation for more details.)
      hint: This usually indicates a problem with the package or the build
      environment.

Right now, the documentation preview is created on every PR. This increases the chance of hitting the rate limit when we actually need to have the documentation preview.

One way of reducing the chance of hitting the rate limit is to filter out the PRs that do not affect the documentation in any way. This can be done by adding paths: block to pull_request_target trigger in documentation-links workflow.

It could look like this:

on:
  pull_request_target:
    types:
      - opened
    paths:
      - "docs/**"
      - "bowtie/__init__.py" # it contains constants required to build docs

[Julian]

Oy, fun.

One way of reducing the chance of hitting the rate limit is to filter out the PRs that do not affect the documentation in any way.

FWIW a PR touching any Python file might affect the docs as the docs are partially collected from docstrings in the source code.

[OptimumCode]

I might be missing something, but it looks like the documentation references just a few other files inside the bowtie:

• bowtie/schemas/io/* files related to IHOP
• implementations/lua-jsonschema/* as a reference implementation (something to change once the test harness is moved out to a separate repo)
• bowtie/_cli.py to collect available commands and arguments

[Julian]

Oh I forgot that the docs were so inadequate :/ Yes that seems right, but e.g. we should have API docs in the contributor's guide for Bowtie contributors, which Sphinx (configured here) can generate, and to do that involves walking over all the files in the package.

In other words: you're right now, but I hope we don't add something that means that this information gets stored in two places because that'll be easy to forget if we add something like ^

[OptimumCode]

Ahh, okay, now I get your point

We could at least mitigate the reaching of the GH API limit when we build the main documentation (not a preview for PR). This can be done by adding a private env variable, which is available at build time