konlpy readthedocs update - hexists/konlpy GitHub Wiki

konlpy readthedocs update

올해 진행한 konlpy 관련 이슈 중 가장 큰 이슈였습니다.
어떻게 해당 이슈를 해결했는지를 정리해봅니다.

문제

#393 pr merge 후 문제가 생겼습니다.
mecab의 설치 경로와 관련된 변경이었는데, 이로 인해 릴리즈된 version이 아닌 master의 mecab을 항상 다운받고 있는 문제를 발견했습니다.
mecab 설치 경로는 version에 따라 구분할 수 있도록 이슈를 남기고 해결 방법을 논의했습니다.

해결 방법

konlpy는 sphinx를 이용해서 문서를 생성합니다.
sphinx가 실행될 때, mecab 설치 스크립트 경로를 version에 따라 유동적으로 설치할 수 있도록 수정했습니다.
주요 수정사항입니다.
- Sphinx-Substitution-Extensions==2022.2.16을 사용했습니다.
  - 해당 extension은 sphinx의 conf.py에 설정해서 사용하 수 있습니다.
  - conf.py에 rst_prolog에 substitution이 필요한 내용을 정의합니다.
  - 본문에서는 block을 'code-block:: bash'으로 지정하고 |variable|을 통해 변수를 사용합니다.
- 코드
```
extensions = [..., 'sphinx_substitution_extensions']

rst_prolog = f"""
.. |release| replace:: v{release}
"""
```
```
.. code-block:: bash
    :substitutions:
    $ bash <(curl -s https://raw.githubusercontent.com/konlpy/konlpy/|release|/scripts/mecab.sh)
```
#399

시도해 본 방법

#1, mecab 설치시 최신 릴리즈 버전을 참조하도록 변경, #395
- master의 파일 대신 최신 릴리즈의 파일을 사용하도록 변경
- release branch 생성해서 모든 mecab의 링크를 release branch를 참고하도록 변경
- 문제점: 서로 다른 version 에 대한 문서에서 MeCab 설치 스크립트를 여전히 동일한 경로를 참조함
- 결론: 다른 해결 방법 찾아보기로 함
#2, parsed-literal을 사용한 방법
- 별도의 extension 없이 가능
- 문제점: indentation이 유지되지 않음(문서 틀이 깨짐)
- 결론: 다른 해결 방법 찾아보기로 함

기타

수정 내용이 바로 반영되진 않습니다.
readthedocs 권한이 필요하고, 해당 권한을 받은지 얼마 되지 않아 테스트 후 반영할 예정입니다.

참고