다른 프로젝트로 연결¶
sphinx.ext.intersphinx를 사용하면 이 프로젝트가 해석하지 못한 참조를 다른 프로젝트의 인벤토리에서 찾습니다. 각 Sphinx 또는 Guidedog 사이트가 게시하는 objects.inv입니다. conf.toml에 프로젝트를 지정하세요.
extensions = ["sphinx.ext.intersphinx"]
[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]
각 항목에는 다른 프로젝트의 페이지 주소와 인벤토리 위치를 적습니다. URL, 소스 폴더 기준의 파일 경로, 또는 주소 아래의 objects.inv를 뜻하는 ""를 사용할 수 있습니다. 목록은 순서대로 시도합니다. Sphinx의 intersphinx_mapping과 같지만 Python의 None 대신 ""를 쓰며, guidedog migrate가 변환합니다.
이후 참조에는 새로운 문법이 필요하지 않습니다.
:func:`len`, :class:`list`, and :ref:`tut-packages` link into Python's documentation.
:ref:`click:testing` looks only in Click's inventory.
:external+python:ref:`tut-packages` never looks in this project.
레이블과 문서 링크는 다른 프로젝트의 제목을 표시하며, “(in Python v3.14)” 같은 도움말을 붙입니다. Sphinx처럼 :doc: 참조에는 프로젝트 이름(:doc:`python:tutorial/index`)이 필요합니다. intersphinx_disabled_reftypes의 기본값이 ["std:doc"]이기 때문입니다.
빌드 시작 시 인벤토리를 가져와 _build/.doctrees/__intersphinx_cache__에 intersphinx_cache_limit일 동안 보관합니다. 기본값은 5일이며 음수이면 계속 보관합니다. 로컬 파일은 매번 읽습니다. Sphinx처럼 URL 리디렉션 후의 디렉터리를 링크 기준으로 사용하고 캐시에 기억하므로 캐시에서도 같은 링크를 만듭니다. 예를 들어 https://werkzeug.palletsprojects.com/objects.inv는 /en/stable/로 이동합니다. intersphinx_timeout은 다운로드별 제한 시간(초)입니다. 접근할 수 없는 프로젝트는 경고하며 참조는 해석되지 않은 채로 남습니다.
Guidedog는 모든 페이지, 레이블, 용어, 객체를 담은 objects.inv를 기록하므로 다른 프로젝트도 같은 방식으로 연결할 수 있습니다.