Read-the-docs 사용법
1. Read-the-docs 관련 패키지를 설치하고 환경변수에 등록해준다.
2. 내 파이썬 프로젝트에 docs 라는 폴더를 만든다.
3. sphinx-quickstart 를 하면 이런 저런 설정을 입력하면서 자동으로 환경을 구성해줌
4. make html 을 하면 빌드를 해줌(이 빌드과정은 read-the-docs 와는 상관없다. html 을 만들어 줌으로써 off-line 으로 확인해볼 수 있는 구조. read-the-docs 는 내 코드를 스스로 빌드한다.)
5. github 와 연동되어야 하므로 github repository 에 내 프로젝트 / Document 파일들을 push 해준다.
6. github 에 업로드하면 read the docs 사이트에서 import 해올 수 있음.
github 에 어떤 파일까지 올려야 하는가?
- read the docs 에 가면 내 document 의 관리 페이지에서 오른쪽 하단의 뱃지를 확인할 수 있다.
- 소스코드 / conf.py / index.rst / makefile 로는 no build 만 뜨는 상황.
- _build 폴더까지 같이 올리자 뱃지가 업데이트 되었다
- (하지만 build 는 필요 없을텐데?)
어떻게 소스코드와 연결할 수 있는가?
- 스핑크스가 모듈을 찾기 위해서, import 할 수 있어야 한다. 다시 말해, build 하는 system path 에 등록되어 있어야 한다는 이야기이다.
스핑크스의 작동원리
- Build 를 돌리면, doc 폴더 안에 내부적으로 document 가 생성되게 된다.
- 이 HTML 파일을 그대로 사용하면 바로 그것이 document 가 되는 것이다.
- 그런데 Read the Docs 웹사이트에서 이게 가능하려면, 그 사이트에서 내 document 코드를 빌드할 수 있어야 한다.
- 그렇다면 그 웹사이트 상에서 내 코드를 빌드할 수 있도록 path 를 등록해 주어야 한다. 상대적인 경로로...
Read the Doc 테마 적용방법
- conf.py 파일에서 html_theme 을 찾아서 코멘트시켜 버리고, 다음 코드를 추가한다.
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# only import and set the theme if we're building docs locally
if not on_rtd:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
주석에 적혀있는 대로, online 에서 바로 테마를 가져오던가, 아니라면 local 에서 build 할때 테마를 적용할 수 있다.
C++ 의 사용
- autodoc 을 사용하기 위해서는 doxygen 과 sphinx 를 연결시켜주는 breathe 라는 도구를 활용하게 된다. 추후에 공부가 더 필요할 것.
외부 라이브러리의 import
- Read the Docs 문서에도 설명되어 있지만, RtD 는 사용자의 파이썬 코드를 한번 컴파일하면서 문서를 빌드하기 때문에 라이브러리 의존성이 있다. 따라서 numpy 와 같은 외부라이브러리를 사용한다면 빌드과정에서 에러가 생기게 된다.
여기에 대한 해결방식은 아래 RtD 문서에서 설명하고 있다.
방식을 간단하게만 설명하면, import 하는 라이브러리들을 mock 모듈을 사용해서 가상으로 import 하는 것이다. 어차피 실제로 돌아갈 필요는 없으니까.
- 여기서 알수 있는건, 코드가 실제로 돌아가서는 안된다는 것이다. 즉, 업로드되는 코드가 클래스 및 함수 형태가 되어야지 __main__() 함수 실행같은것을 코드상에 포함시켜서 실제로 돌아가면 에러를 발생시키게 된다.
한글 사용
- conf.py 파일에서 language 옵션을 'ko' 로 주게되면 기본메뉴가 한글로 뜨게 되는데 큰 의미는 없다.
- Sphinx 는 유용한 Internationalization 기능을 지원하는데, 하나의 언어로 작성된 문서를 다른 언어로 번역하여 빌드할 수 있다.
- 그러나, 사실 개인이 진행하는 소규모 프로젝트에서 이 정도로 문서를 구성하는 것은 무리한 일이 될 수 있어서, 기본적으로 영문이나 한글 둘중의 하나를 선택하여 작성하는 정도로 마무리하려고 한다.
- 한글을 꼭 사용하고 싶으면 python 소스파일 상단에는
#-*- coding: utf-8 -*-
를 추가하고, conf.py 의 source_encoding 옵션을
source_encoding = 'cp949'
로 바꿔주면 한글 문서작성 및 autodoc 이 가능해진다.
- html 은 온라인빌드/오프라인 빌드 둘다 잘 되는데, pdf 빌드가 깨진다. 이 옵션도 conf.py 에서 잡아주면 될것 같은데 당장 꼭 필요한 옵션같지는 않다...