hossam.make_docs¶

hossam.make_docs ¶

API 레퍼런스 문서 생성 모듈

학생이 자신의 helpers 폴더에 작성한 소스 코드의 docstring 을 읽어 HTML API 레퍼런스 문서를 만들어 준다. 이 저장소가 GitHub Actions 에서 문서를 배포할 때 쓰는 방식(mkdocs + mkdocstrings)을 그대로 개인 PC 에서 실행하는 것이므로, 결과물의 모양은 공식 문서와 같다.

mkdocs 설정 파일이나 문서 페이지를 직접 만들 필요는 없다. 소스 폴더를 훑어 공개 모듈(_ 로 시작하지 않는 최상위 *.py)마다 페이지와 목차를 자동으로 생성하므로, 파일을 추가하거나 지우면 문서도 따라 바뀐다.

사용 방법 (학생)

from hossam import make_api_docs

make_api_docs("helpers", "helpers-docs")

문서 생성에 필요한 패키지(mkdocs 계열)가 없으면 처음 한 번 자동으로 설치한다. 미리 설치해 두려면 다음과 같이 한다.

pip install "hossam[docs]"

make_api_docs ¶

make_api_docs(
    src_dir,
    out_dir,
    site_name=None,
    open_browser=False,
    force=False,
    install=True,
    verbose=False,
)

소스 폴더의 docstring 을 읽어 HTML API 레퍼런스 문서를 생성한다.

Parameters:

Name	Type	Description	Default
`src_dir`	`str`	문서화할 소스 폴더 경로 (예: `helpers`)	required
`out_dir`	`str`	문서가 생성될 폴더 경로 (예: `helpers-docs`)	required
`site_name`	`str`	문서 상단에 표시할 제목. 생략하면 `<폴더명> API Docs`	`None`
`open_browser`	`bool`	생성 후 기본 브라우저로 문서를 열지 여부	`False`
`force`	`bool`	출력 폴더에 다른 파일이 있어도 진행할지 여부	`False`
`install`	`bool`	필수 패키지가 없을 때 자동으로 설치할지 여부	`True`
`verbose`	`bool`	빌드 상세 로그를 모두 출력할지 여부	`False`

Returns:

Name	Type	Description
`str`	`str`	생성된 문서의 시작 페이지(index.html) 경로

Raises:

Type	Description
`FileNotFoundError`	소스 폴더가 없거나 문서화할 `*.py` 가 없는 경우
`ValueError`	출력 폴더가 소스를 지울 수 있는 위치인 경우
`RuntimeError`	패키지 설치 또는 문서 빌드에 실패한 경우