Sphinx-4.4 진화형 기능 사용

방금 Sphinx-24.0이 나왔습니다.
스펙스는 2개월마다 정기 발매를 목표로 하기 때문에 기본적으로 예정대로 발매된다.
2.40 때 autodoc 주위의 기능이 크게 개선되었다.나는 이 보도에서 그 개선점을 총결하고 싶다.

변수 초대에 대응

autodoc: Support type annotations for variables

#7051: autodoc: Support instance variables without defaults (PEP-526)

지금까지 코드의 변수 인덱스는 문서화되지 않았지만 2.4에서 문서로 출력됩니다.
현재형 정보는 대규모 프로그램에서 빠질 수 없는 정보를 쓰는 것이다.편성형 정보는 당신과 개발팀을 도울 뿐만 아니라 프로그램 라이브러리를 이용하는 사람들도 도울 수 있다.
또한 초기 값이 없는 유형 선언PEP-526도 지원됩니다.다음과 같이 정의되면 Starship.captain 및 Starship.damage는 템플릿이 있는 인스턴스 변수로 문서화됩니다.

class Starship:
    captain: str
    damage: int

이 변경에 따라 파이썬 3.7에서 가져온 데이터classss도 문서로 만들 수 있습니다.

type commeent 형식의 변형 대응

#2755: autodoc: Support type_comment style (ex. # type: (str) -> str )
annotation (python3.8+ or typed_ast <https://github.com/python/typed_ast> _
is required)

이전부터 사용된 type commeent 형식 (예: # type: (str) -> str 의 형식 개편을 지원합니다.장기적으로 유지보수하는 프로젝트에서 이 기능은 반드시 유용할 것이다.
또한, 파이썬 3.7 typedast를 설치하십시오.

본문에 형식 문서를 표시하는 기능을 가져왔습니다

#6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints . It shows
typehints as object description if autodoc_typehints = "description" set.
This is an experimental extension and it will be integrated into autodoc core
in Sphinx-3.0

3.0 이후에 정식으로 도입된 기능을 추가한 전단지sphinx.ext.autodoc.typehints의 확장.
이 확장자를 불러오면 설정autodoc_typehints을 지정할 수 있습니다"description".autodoc_typehints는 함수와 방법을 문서화할 때 유형 정보를 어떻게 표시하는지 조정하는 방법이다.
이번 수정을 이해하기 위해 오리지널 기능을 포함한 내용을 소개하고 싶습니다.autodoc_typehints에는 3가지 모드(새 설정 포함)가 있습니다.다음 함수의 문서를 예로 들면 각 모델의 전환 결과를 살펴봅시다.

def hello(name: str, age: int) -> str:
    """Hello world!

    :param name: Your name
    :param age: Your age
    :returns: greeting message
    """

signature 모드

기본 설정autodoc_typehints = "signature"에는 함수 문서의 정의 표시줄에 유형 초대장이 직접 표시됩니다.

간단한 함수라면 이 상태에서 쉽게 읽을 수 있지만 매개 변수가 많은 함수와 방법은 읽기 어렵다.예를 들어 tornado 프로젝트에서다음 문서가 생성되었습니다..

none 모드

다른 설정 autodoc_typehints = "none" 은 함수 문서의 정의 표시줄에서 형식 초대장을 삭제합니다.

잘 나오네.이 옵션은 함수 주석에서 매개 변수를 스스로 설명하는 데 도움이 됩니다.프로그램과 주석에서 두 곳에 유형 정보를 써야 하기 때문에 지루하지만 읽기 쉬운 문서를 쓸 수 있다.
Google 형식과 Numpy 형식에는 함수 리뷰에 모태 시뮬레이션을 기록하는 문화가 있기 때문에 이 옵션과 일치한다고 할 수 있습니다.

description 모드(신규)

또한 이번 추가 설정autodoc_typehints = "description"은 함수 문서의 본문 부분에 유형 근사 정보를 보여 줍니다.

어떤 형식이 읽기 쉬운지는 쓰는 프로그램의 규모에 따라 차이가 있지만, 개인적으로는 이번에 추가된 설정이 읽기 쉽다고 생각한다.
experimental이지만 특별히 심각한 버그가 발견되지 않으면 3.0에 정식으로 적용됩니다.
만약 무슨 이상한 점이 있으면 나에게 잘못을 보고할 수 있다면 나는 매우 고마울 것이다.
※ 새로운 설정은 현재sphinx.ext.autodoc.typehints 로드 확장 시에만 유효합니다.

총결산

Sphinx-24..0

출시

autodoc 주위의 개선 노력

sphinx.ext.autodoc.typehints 추가되었습니다.피드백을 기대하십시오

다른 기능도 추가되어 장애가 발생했습니다.
자세한 내용은 CHANGES