pythhon 패키지의 문서를 쉽게 만들어github 페이지에 올리는 방법

python에 자신의 포장PyPI을 쓰려면'아, README를 써야 해요'라고 써야 하나요?코드와 시험은 힘들지 않겠지만 문서 작성은 번거롭다.
문서 자동 제작 도구도 고려해 봤는데pydoc의 디자인은 그것Sphinx 설정이 매우 번거롭다.
여러 가지 검색을 해봤는데 pdoc3 이 자동 제작 도구가 간단하고 디자인도 별로여서 썼어요.
성과물은 이쪽에 있다.
https://atu4403.github.io/adash/adash/

이른바 pdoc3

pdoc fork에서 나온 포장은 pdoc와는 다른 물건입니다.
당사(pdoc)
mitmproxy/pdoc: API Documentation for Python Projects
분가(pdoc3)
pdoc3/pdoc: Auto-generate API documentation for Python projects
단, pip install pdoc3에 설치하면 cli 명령pdoc을 Asain으로 설정합니다.그러니까 경쟁.
이 두 항목은 좋은 관계가 아닌 것 같다.
pdoc vs. pdoc3 | PythonRepo
하지만 현재pdocdoctest의 표시가 좋지 않은 것 같아서 여기pdoc3를 사용합니다.pdoc3 원본 코드에 docstring을 쓰면 이를 바탕으로 자동으로 만들어집니다.집행은 간단한 지령이다.
docstring의 스타일은 numby, 구글,reST 등을 지원합니다.

차리다

docstring 쓰기

좋은 프로젝트라면 문서도 그에 상응하는 수준을 요구하지만 아주 작은 프로젝트이기 때문에 기능성이 우선이다.
문서에는 함수 형식, 매개 변수 형식, 사용 방법이 충분하기 때문에 모드와doctest만 씁니다.
typing-유형 힌트 지원 - Python 3 문서
doctest - 상호 작용 테스트 예제 - Python 3 문서

def replace_all(s: str, obj: dict) -> str:
    """複数のreplace
    Example:
        >>> _obj = {"円": ".", "銭": ""}
        >>> replace_all("3円00銭", _obj)
        '3.00'
        >>> _obj = {"[△▲]": "-", "[,、]": ""}
        >>> replace_all('▲12,345', _obj)
        '-12345'
        >>> replace_all('△12、345', _obj)
        '-12345'
    """
    # 実装部分

실례는 다음과 같다.
https://github.com/atu4403/adash/blob/main/src/adash/string_util.py

README 읽기

docstring 정보만 부족하면 문서에 README를 삽입할 수 있습니다.
프로젝트 원본 바로 아래__init__.py의 시작에 주석을 추가합니다.

"""
.. include:: ../../README.md
"""
# 以下普通に実装
from foo import bar

../../README.md는 __init__.py에서 온 상대적인 경로이다.나는 src 레이아웃을 사용하기 때문에 이렇게 되고 그렇지 않으면 ../ 줄어든다.

pdoc3 설치

pip install pdoc3

문서 작성

pdoc --html --output-dir docs --force src/{プロジェクト名}

이 동작을 실행하면 docs 디렉터리에 > 문서를 만듭니다.
src 레이아웃src/이 아니면 필요 없어요.
문제 없으면 github로 push 가.

github 페이지의 작업

push 뒤의 창고github 페이지에서 settings→pages를 열고 Branch와docs만 선택하십시오.

이렇게 하면 완성될 것 같은데 표시된 링크를 열면 404가 됩니다.
pdoc를 제작할 때 src 판면 디자인의 폐단으로 docs 아래에 또 한 층이 형성된 것 같습니다.

.
├── LICENSE
├── README.md
├── docs
│   └── adash
│       ├── download.html
│       ├── index.html
│       ├── proportion.html
│       └── string_util.html
├── poetry.lock
├── pyproject.toml

URL의 계층 구조를 직접 파고들면 접근이 잘 되기 때문에 특별한 수정은 하지 않는다.
URL이 좀 역겨워요. 이번에 만든 문서가 여기 있어요.
https://atu4403.github.io/adash/adash/

자동화

(2021/11/06 보충)
상기 절차에서 문서를 업데이트할 때마다 pdoc 명령을 사용하여commmit&push를 진행하는 시간이 있습니다.github actions로 이걸 자동화합니다.
https://github.com/peaceiris/actions-gh-pages
이 작업을 사용하여 지정된 디렉토리를 브랜치gh-pages로 설계합니다..github/workflows/deploy.yml.

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.9
      - name: Build
        run: |
          pip install pdoc3
          pdoc --html --output-dir tmp --force src/{ここにproject-name}

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./tmp

ここにproject-name의 부분을 프로젝트 이름에 따라 다시 씁니다.
이상은push일 때 gh-pages 지점에서 자동으로 문서를 만듭니다.
settings→pages 설정을 gh-pages와 루트로 변경하면 완성됩니다.