엄범


docstring 작성 포맷

https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format

google style은 다음과 같은데 타입 적는게 :가 아니라 괄호 안에 들어가서 마음에 안들고, 들여쓰기 때문에 가로축도 많이 차지하고, VSCode에서 힌트 팝업으로 보여줄 때도 bold나 글꼴 크기같은게 안예쁘게 들어간다.

```py

Args:

    path (str): 설명

Returns:

    int: 설명

```

Sphinx와 잘 붙는건 reST 스타일인데, ``py :param v1:``과 ``py :type v1:``을 따로 적어주어야 한다는 점이 마음에 들지 않고 가독성도 썩 좋지 않은 것 같다.

가독성은 Numpydoc 스타일이 괜찮고, 그나마 제일 마음에 드는 스타일.

https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard


sphinx

http://alifejon.blogspot.com/2016/02/sphinx-python-api.html

스핑크스에 sphinx.ext.napoleon 플러그인을 추가하면 NumPy 스타일의 독스트링을 사용할 수 있음.


1. sphinx-quickstart    # conf.py 및 기본 구조 생성

```

D:\Source\RAPTs\docs
λ sphinx-quickstart.exe
...
```

docs/source/conf.py 설정

sphinx에서 reST말고 .md도 파싱하기


2. sphinx-apidoc    # .rst 파일 생성

```

D:\Source\RAPTs
λ sphinx-apidoc.exe -f -o docs/source RAPT
```
쓸만한 옵션은 `` -f, -o, -e``

sidebar 설정

`` source/index.rst``에서 사이드바에 나타낼 디렉토리 이름 추가
```
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   src
```

3. make.bat html

```

D:\Source\RAPTs\docs
λ make.bat html
```