Guidedog / 문서 0.2.0

코드베이스 문서화¶

공개 이름에는 계약이 필요하다. 입력, 결과, 소유권, 실패 조건을 설명한다. 시그니처만으로는 설명서가 되지 않는다.

Odin¶

odin_autoapi_dirs = ["../../lib"]
odin_autoapi_root = "api"
odin_autoapi_options = ["members", "undoc-members"]

Guidedog은 Odin 파서로 소스를 읽는다. 문서화할 패키지를 컴파일하거나 실행하지 않는다. 생성 페이지는 문서 그래프와 객체 목록에 들어간다. 저장소의 별도 API 프로젝트는 docs/api이다. 지시문, 시그니처, 옵션은 Odin 문서화을 참고한다.

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

Guidedog은 Python 소스를 가져오기 없이 파싱하여 import 부작용을 피한다. 따라서 실행 중 생성되는 객체는 빠질 수 있다. 공개 인터페이스에 속한다면 명시적으로 설명한다. 정확한 탐색 규칙은 autodoc으로 Python 문서 작성하기을 참고한다.

생성한 objects.inv를 사이트와 함께 게시한다. 다른 프로젝트가 intersphinx 매핑으로 이름을 해결할 수 있다. 재현 가능한 빌드에는 명시적인 매핑을 쓴다. 다른 프로젝트로 연결를 참고한다.