Fine-grained Configuration of check_crossrefs

[thetianshuhuang]

Adds a few features to allow for more fine-grained control of check_crossrefs.

• Fix for check_crossrefs is not a valid option #43: Save check_crossrefs as a class attribute instead of via global_options, and pass to PythonRelXRefOptions via constructor instead of via assignment to work with newer versions of mkdocstrings-python.
• Add a check_crossrefs_exclude argument, which allows users to pass a list of regex patterns to exclude from crossref checking; this is motivated by the observation that crossref checking overhead is usually negligible, except when importing particularly expensive libraries, e.g., pytorch.
• Updated documentation for these changes.

[analog-cbarber]

When I try running the tests on my machine (a Mac M1) under python 3.13, I get an error in the integration test:

% make pytest     
conda run -n mkxref-dev --no-capture-output pytest -sv -ra  tests
============================================================================== test session starts ===============================================================================
platform darwin -- Python 3.13.3, pytest-8.4.0, pluggy-1.6.0 -- /Users/Christopher.Barber/miniconda3/envs/mkxref-dev/bin/python3.13
cachedir: .pytest_cache
rootdir: /Users/Christopher.Barber/ws/mkdocstrings-python-xref
configfile: pyproject.toml
plugins: cov-6.1.1
collected 5 items                                                                                                                                                                

tests/test_crossref.py::test_RelativeCrossrefProcessor PASSED
tests/test_crossref.py::test_substitute_relative_crossrefs PASSED
tests/test_crossref.py::test_doc_value_offset_to_location PASSED
tests/test_handler.py::test_handler PASSED
tests/test_integration.py::test_integration FAILED

==================================================================================== FAILURES ====================================================================================
________________________________________________________________________________ test_integration ________________________________________________________________________________

tmpdir = local('/private/var/folders/69/_vd0mbk92_xcm1nytg1zbvfm0000gp/T/pytest-of-Christopher.Barber/pytest-3/test_integration0')

    def test_integration(tmpdir: PathLike) -> None:
        """An integration test that runs mkdocs on a tiny sample project and
        grovels the generated HTML to see that the links were resolved.
        """
    
        site_dir = Path(tmpdir).joinpath('site')
        mkdocs_cmd = [
            'mkdocs',
            'build',
            '-f',
            str(test_project_mkdocs),
            '-d',
            str(site_dir)
        ]
        result = sp.run(
            mkdocs_cmd,
            stdout=sp.PIPE,
            stderr=sp.PIPE,
            encoding='utf8',
            check=False,
        )
    
        assert result.returncode == 0
    
        m = re.search(
            r"WARNING.*file://(/.*/myproj/bar.py):(\d+):(\d+):\s*\n\s*Cannot load reference '(.*)'",
            result.stderr
        )
>       assert m is not None
E       assert None is not None

tests/test_integration.py:83: AssertionError
================================================================================ warnings summary ================================================================================
tests/test_handler.py::test_handler
  /Users/Christopher.Barber/miniconda3/envs/mkxref-dev/lib/python3.13/site-packages/mkdocstrings_handlers/python/_internal/handler.py:91: DeprecationWarning: The `mdx` argument must be provided (as a keyword argument).
    super().__init__(**kwargs)

tests/test_handler.py::test_handler
  /Users/Christopher.Barber/miniconda3/envs/mkxref-dev/lib/python3.13/site-packages/mkdocstrings_handlers/python/_internal/handler.py:91: DeprecationWarning: The `mdx_config` argument must be provided (as a keyword argument).
    super().__init__(**kwargs)

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
============================================================================ short test summary info =============================================================================
FAILED tests/test_integration.py::test_integration - assert None is not None
==================================================================== 1 failed, 4 passed, 2 warnings in 5.88s =====================================================================
ERROR conda.cli.main_run:execute(125): `conda run pytest -sv -ra tests` failed. (See above for error)
make: *** [Makefile:122: pytest] Error 1
(mkxref-dev) ws/mkdocstrings-python-xref % python --version
Python 3.13.3

[thetianshuhuang]

Ah, probably should have properly run the tests...

Turns out I set the default to the false-y

self.check_crossrefs = config.options.pop('check_crossrefs', None)

instead of

self.check_crossrefs = config.options.pop('check_crossrefs', True)

Tests running and passing now on my end.