ReadtheDocs에 문서를 업로드하려면 .rst파일 형식으로 변환해서 업로드해 줘야 한다. .rst 파일대신 .md파일을 통해 문서를 업로드하는 방법에 대해 이야기해 보려 한다(이 글에서는 shpinx autodocs에 대한 이야기는 하지 않는다).

소스 코드는 이곳에서 볼 수 있다.

순서

이 글에서는 설치부터 시작해서 마크다운 문서 업로드 하는 것으로 마무리 하려한다. 이 글의 순서는 아래와 같다.

  1. Shpinx 설치
  2. Shpinx 세팅&빌드
  3. 마크다운 extension 추가
  4. 파일 등록
  5. ReadtheDocs에 import

1. Shpinx 설치

설치는 pip를 통해 간단하게 설치할 수 있다.

$ pip install Sphinx

2. Shpinx 세팅&빌드

ReadtheDocs에 업로드할 때 보통 docs/ 라는 폴더를 참고하여 빌드한다. 이를 위해 프로젝트의 최상위 에 docs/라는 디렉터리를 만들어준다. 그 다음 shpinx-quickstart 를 통해 간단한 boilerplate(?)를 만들어준다.

$ mkdir docs
$ cd docs
$ sphinx-quickstart

sphinx-quickstart 명령어를 실행하면 아래와 같은 옵션 선택 문구가 출력된다.

> 원본과 빌드 디렉토리 분리 (y/n) [n]: y

> 프로젝트 이름: test
> 작성자 이름: ybeen
> 프로젝트 릴리스 []:

원본과 빌드 디렉토리 분리 (y/n) [n]:

이 옵션을 선택하면, source 폴더와 build 폴더를 별도로 생성하여 원본과 빌드 디렉토리를 분리할 수 있다.

source 폴더에는 문서 파일과 빌드 설정 파일이 저장되며, build 폴더에는 빌드된 문서 파일이 저장된다. 이렇게 원본과 빌드를 분리하면, 빌드된 파일이 손상될 위험을 줄일 수 있고, 더욱 체계적인 프로젝트 관리가 가능해진다.

그러나, source 폴더와 build 폴더를 분리하면 프로젝트 폴더의 구조가 복잡해질 수 있다. 또한, 빌드 시간이 약간 늘어날 수 있다. 따라서, 프로젝트의 규모와 목적에 따라 잘판단하여 선택해야한다.

나의 경우는 y를 선택하여 분리해줬다.

프로젝트 릴리스 [ ]:

이 값을 설정하면 프로젝트의 버전 정보를 관리할 수 있으며, 문서 내에서 자동으로 버전 정보를 생성할 수 있다. 1.0.0과 같은 방식으로 입력하면 되며, 그냥 엔터를 누르면 아무 값도 입력되지 않고 빈 값으로 설정된다. 이 경우, Sphinx는 프로젝트 릴리스 값을 생성하지 않으며, 문서 내에서 버전 정보를 사용할 때 수동으로 입력해야 한다.

하지만, 버전 정보를 설정하지 않고 빈 값으로 둔 경우에도 Sphinx를 사용하는 데에는 문제가 없기 때문에 나는 그냥 넘어갔다.

위 과정이 끝났다면 아래와 같은 구조로 파일들이 생긴 것을 확인할 수 있다.

.
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

빌드

빌드 과정 또한 정말 간단하다. 위 세팅 과정에서 생긴 Makefile 을 이용해 빌드하면 된다.

$ make html

이 명령어가 잘 실행되었다면 아래와 같이 파일이 더 많이 생긴 것을 확인할 수 있다.

.
├── Makefile
├── build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│       ├── _sources
│       │   └── index.rst.txt
│       ├── _static
│       │   ├── _sphinx_javascript_frameworks_compat.js
│       │   ├── alabaster.css
│       │   ├── basic.css
│       │   ├── custom.css
│       │   ├── doctools.js
│       │   ├── documentation_options.js
│       │   ├── file.png
│       │   ├── jquery-3.6.0.js
│       │   ├── jquery.js
│       │   ├── language_data.js
│       │   ├── minus.png
│       │   ├── plus.png
│       │   ├── pygments.css
│       │   ├── searchtools.js
│       │   ├── sphinx_highlight.js
│       │   ├── translations.js
│       │   ├── underscore-1.13.1.js
│       │   └── underscore.js
│       ├── genindex.html
│       ├── index.html
│       ├── objects.inv
│       ├── search.html
│       └── searchindex.js
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

build/html/index.html 을 확인해보면 정말 안이쁜 웹페이지가 생선된 것을 확인해볼 수 있다. 이 파일이 우리의 ReadtheDocs로 올라갈 파일이다. 하지만 여기서 우리가 주로 신경쓸 파일을 source 폴더에 있는 conf.py 와 index.rst 파일이다. index.html 은 그저 template일 뿐이므로 크게 신경쓸 일이 없다.

3. 마크다운 extension 추가

Sphinx는 기본적으로 .rst 파일만 업로드할 수 있다. 여기에 .md 파일도 업로드 가능하게 하려면 myst를 설치해줘야 한다.

$ pip install myst_nb

설치 후 conf.py 에서 extensions 필드와 source_shuffix 필드를 다음과 수정해줘야 한다.

extensions = ['myst_nb']
source_suffix = ['.rst', '.md']

위 과정을 완료했다면 이제 conf.py 와 같은 위치에 requirements.txt를 만들어 myst_nb를 추가해준다.

이제 문서에 .md 파일을 업로드할 수 있다.

한글이 포함된 마크다운 파일 업로드 시

한글이 추가된 마크다운 파일을 업로드시에는 Latex Unicode Error가 발생하게 된다. 이를 해결해주기 위해 conf.py에 아래와 같은 코드를 추가해준다.

latex_engine = 'xelatex'

latex_elements = {
    'fontpkg': r'''
    \setmainfont{DejaVu Serif}
    \setsansfont{DejaVu Sans}
    \setmonofont{DejaVu Sans Mono}
    ''',
    'inputenc': '',
    'utf8extra': '',
}

latex_engine 변수는 빌드에 사용할 LaTeX 엔진을 설정합니다. 이 변수는 pdflatex, xelatex, lualatex 중 하나의 값을 사용할 수 있다. 이 예제에서는 xelatex를 사용하도록 설정했다.

latex_elements 변수는 LaTeX 템플릿에 전달할 설정을 포함한다. 이 변수를 사용하여 inputenc 패키지 설정을 비활성화할 수 있다. inputenc 패키지 설정을 비활성화하면, LaTeX 템플릿에서 유니코드 문자셋을 처리하는 방법을 변경할 수 있다.

4. 파일 등록

업로드할 파일의 등록은 index.rst 파일에서 이루어진다. 우선 docs/source/ 디렉토리 아래에 원하는 이름의 폴더를 만들어주고, 여기에 마크다운 파일을 넣어준다. 이후 index.rst 다음과 같이 수정해주면 된다.

.. toctree::
   :maxdepth: 2
   :caption: A:
   
   A/a1.md
   A/a2.md

위에서는 A 라는 디렉터리를 생성한 후 a1.md 파일과 a2.md 파일을 위치해 놓은 후 등록한 예시이다. 이로써 이제 ReadtheDocs에 등록할 준비를 모두 마쳤다.

5. ReadtheDocs에 import

Github 레포를 하나 만들어 위에서 만들었던 프로젝트를 push 해준다. 그후 ReadtheDocs 페이지에서 Github으로 로그인해 준다. 그럼 import할 레포를 고르게되는데 방금 만들었던 레포를 선택해주고 build 버튼을 누르면 빌드가 시작된다.

하지만 빌드가 실패할 것이다. 왜냐면 myst_nb가 설치가 안되었기 때문이다. 이를 해결하기 위해서 설정 > 고급 설정 > Requirments file 에 아까 만들었던 requirements.txt 의 경로를 입력해 준다. 나의 경우 docs/source/requirements.txt 라고 입력하였다. 저장 후 다시 빌드가 되면 정상적인 페이지가 보이는 것을 볼 수 있다. 내 페이지 예시는 여기서 볼 수 있다.

References