Guidedog 설명서 0.2.0
언어
이 페이지의 내용
Guidedog / 문서 0.2.0

autodoc으로 Python 문서 작성하기

Guidedog는 소스 코드를 읽어 Python 문서를 생성합니다. 패키지를 import하지 않습니다. docstring과 시그니처는 문서 그래프에 포함됩니다. 실행 중에만 생성되는 객체는 명시적으로 설명해야 합니다. 이는 의도적으로 정한 경계입니다.

설정하기

확장을 지정하고 소스 폴더를 기준으로 패키지의 위치를 Guidedog에 알려 주세요. Python에서 sys.path를 설정하는 것과 같습니다:

extensions = ["sphinx.ext.autodoc"]
autodoc_source_paths = ["../src"]

guidedog migrate는 sys.path.insert(0, os.path.abspath('..'))처럼 conf.py에서 패키지 경로를 설정하는 줄을 읽고 autodoc_source_paths를 작성합니다. 다른 위치에 설치된 패키지는 해당 폴더를 추가해야 찾을 수 있습니다. 예를 들어 의존 패키지의 소스 체크아웃 폴더를 지정할 수 있습니다. Guidedog는 Python의 site-packages를 검색하지 않습니다.

이제 지시문을 Sphinx와 같은 방식으로 사용할 수 있습니다:

.. automodule:: shop.cart
   :members:
   :show-inheritance:

.. autoclass:: shop.Cart
   :members: add, remove
   :inherited-members:

Sphinx 9.1에서 지원하는 모든 옵션을 같은 의미로 사용할 수 있습니다: :members:, :undoc-members:, :private-members:, :special-members:, :inherited-members:, :exclude-members:, :member-order:, :show-inheritance:, :imported-members:, :ignore-module-all:, :class-doc-from:, :no-value:, :annotation:, :no-index:, :no-index-entry:, :synopsis:, :platform:, :deprecated:. autodoc_default_options를 취소하는 no- 형식도 지원합니다.

설정

이 conf.toml 설정은 Sphinx와 이름, 값, 기본값이 같습니다.

autodoc_source_paths

Guidedog 전용 설정입니다. Python 모듈을 찾을 디렉터리를 소스 디렉터리 기준의 상대 경로로 검색 순서대로 지정합니다. 이 디렉터리 아래의 파일만 읽으며, 밖으로 이어지는 심볼릭 링크는 거부합니다.

autoclass_content

클래스를 설명할 docstring을 지정합니다. "class"(기본값), "init", "both" 중에서 선택합니다.

autodoc_class_signature

"mixed"(기본값) 또는 "separated"입니다. 후자는 __init__를 별도 메서드로 문서화합니다.

autodoc_default_options

모든 지시문에 적용할 옵션 표입니다. 예를 들어 members = true 또는 member-order = "bysource"를 지정합니다. 값이 false이면 해당 옵션을 제외합니다.

autodoc_docstring_signature

true(기본값): docstring의 첫 줄이 name(args) -> result 같은 형식이면 시그니처로 사용합니다.

autodoc_inherit_docstrings

true(기본값): docstring이 없는 멤버는 기반 클래스의 docstring을 상속합니다.

autodoc_member_order

"alphabetical"(기본값), "groupwise", "bysource" 중에서 선택합니다.

autodoc_preserve_defaults

false(기본값): 기본값을 repr() 표현으로 표시합니다. true이면 소스에 쓰인 형태를 유지합니다.

autodoc_typehints

"signature"(기본값), "description"(:type: 및 :rtype: 필드 사용), "both", "none" 중에서 선택합니다.

autodoc_typehints_description_target

"all"(기본값), "documented", "documented_params" 중에서 선택합니다.

autodoc_typehints_format

"short"(기본값) 또는 "fully-qualified"입니다.

autodoc_use_type_comments

true(기본값): # type: 주석을 타입 어노테이션으로 취급합니다.

strip_signature_backslash

Sphinx처럼 시그니처의 역슬래시를 두 번 씁니다.

autodoc_mock_imports, autodoc_type_aliases, autodoc_warningiserror

설정은 허용됩니다. 모듈을 임포트하지 않으므로 모킹이 필요하지 않습니다. 타입 별칭은 적용하지 않습니다.

Guidedog가 Python의 동작을 판단하는 방법

이름은 Python의 바인딩 규칙에 따라 해석합니다. 패키지의 __init__.py에 있는 from .app import Flask는 flask.Flask를 flask/app.py에 정의된 클래스로 연결합니다. autodoc은 이를 :canonical: flask.app.Flask로 표시합니다. 기반 클래스도 같은 방식으로 찾고, 메서드 결정 순서는 Python과 같은 규칙으로 계산합니다. 상속된 멤버는 기반 클래스의 소스에서 가져옵니다. if TYPE_CHECKING: 안에서만 임포트한 이름은 실행 시 존재하지 않으므로, 해당 이름을 쓰는 어노테이션은 Sphinx와 마찬가지로 원문을 유지합니다.

docstring은 Python이 저장할 문자열과 같습니다. 이스케이프를 처리하고 Python 3.13 컴파일러와 같은 규칙으로 들여쓰기를 제거합니다. 속성 설명은 Sphinx 분석기와 같은 위치에서 읽습니다. 대입문 뒤나 바로 위의 #: 주석, 그리고 대입문 바로 다음의 문자열 리터럴입니다. 시그니처는 def에서 가져옵니다. 클래스는 Python의 탐색 규칙에 따라 메타클래스의 __call__, __new__, __init__를 사용합니다. dataclass와 NamedTuple은 필드를 사용합니다. @overload 변형은 구현의 시그니처를 대신합니다.

Python을 실행하지 않고는 알 수 없는 정보

소스만으로 Python의 동작을 알 수 없으면 Guidedog는 해당 객체의 이름을 밝혀 알립니다. 문서화할 수 없으면 경고를 냅니다. Sphinx보다 적은 정보로 문서화했다면 -v에서 볼 수 있는 안내를 남깁니다.

  • 컴파일된 모듈(.so, .pyd)에는 읽을 소스가 없으므로 객체를 찾을 수 없습니다.
  • 코드를 실행해 얻는 값(app = Flask(__name__), now = datetime.now())에는 :value:가 없습니다. 계산이 필요한 기본값은 소스의 표기를 유지합니다.
  • 소스 경로 밖의 데코레이터(@click.command())가 만든 함수는 데코레이션 전의 함수를 기준으로 문서화합니다.
  • 소스 경로 밖의 패키지에 있는 클래스는 임포트한 경로로 이름을 표시합니다. 이 경로는 실제 정의 모듈과 다를 수 있습니다. 멤버, 생성자 시그니처, 상속할 docstring은 알 수 없습니다.
  • 내장 타입의 docstring은 알 수 없습니다. 따라서 자체 docstring 없이 dict의 docstring을 상속할 메서드는 제외합니다.
  • autodoc 이벤트(autodoc-process-docstring, autodoc-skip-member 등)를 처리하는 Python 확장은 실행하지 않습니다.
  • 실제 코드 수준을 훨씬 넘는 깊은 중첩은 분석하지 않고 autodoc.too_deep 경고를 냅니다. Python 자체도 200단계의 괄호 중첩을 거부합니다. Guidedog는 수백 개 피연산자로 이어진 + 연산도 거부합니다.
  • 처리가 계속 늘어날 수 있는 작업에는 한도가 있습니다. 임포트와 별칭을 따라 이름을 찾을 때 한 경로는 48단계, 전체는 100,000단계까지입니다. 타입 별칭과 상수는 10,000단계까지 확장하며, 그 뒤에는 소스 표기를 유지합니다. 클래스의 MRO는 100개 클래스까지 추적합니다. 지시문 하나가 생성하는 지시문은 최대 10,000개이며, 초과하면 autodoc.limit 경고를 냅니다. 마지막 한도에 도달하는 것은 자신의 이름으로 자신을 포함하는 클래스입니다.

누락된 패키지의 소스 디렉터리를 autodoc_source_paths에 추가하면 이러한 제약 대부분을 해결할 수 있습니다.

다시 빌드하기

autodoc 지시문이 읽은 모든 Python 파일은 페이지의 의존성으로 기록됩니다. 파일을 수정하면 다음 빌드에서 페이지를 다시 읽습니다. 객체를 찾지 못한 페이지는 매번 다시 읽으므로, 소스에 객체가 추가되면 바로 인식합니다.

보안

문서 빌드에서는 프로젝트 코드를 실행하지 않습니다. Guidedog는 Python 소스를 텍스트로 읽고 include와 같은 경로 제한을 적용합니다. autodoc_source_paths 아래만 읽으며, 밖으로 이어지는 링크는 따라가지 않습니다.