Sphinx로 TIL 문서 페이지 만들기

Today I Learned 을 언제부터인가 쓰고 있었는데 Markdown으로 작성하고 Git으로 관리하니 매우 편했다.

하지만 다시 보고 싶을 때 검색이 용이하지 않아서 뭔가 검색할 수 있는 페이지를 만들면 좋겠다 싶어서 이것 저것 찾아보았다.

Markdown을 정적 웹 페이지로 만들어주는 툴은 많았지만(심지어 이 블로그도 Markdown 기반...) 뭔가 안써본걸 써보고 싶었다.

그렇게 알아보던 중 Python 문서화 툴인 Sphinx를 사용할 수 있지 않을까라는 막연한 생각에 찾아봤는데 역시나 가능했다.

Sphinx???

Sphinx는 Python Documentation Generator 이다.
Python Code의 docstring을 가져와 자동으로 문서화해주는 라이브러리인데 설정도 아주 손쉽게 할 수 있어서 널리 사용되고 있다.

또한 reStructuredText 문서도 테마에 맞는 HTML로 만들어주고 검색페이지도 만들어 줘서 장점이 한둘이 아니다.

그리고 Read The Docs를 사용하면 무료로 호스팅도 가능하다.

자, 그럼 셋팅을 해보자

일단 TIL 디렉토리는 아래처럼 되어있다.

.
├── README.md
├── mysql
│   └── mysql.md
├── python
│   └── python.md
└── vim
    └── vim.md

그리고 Sphinx를 설치하고 sphinx-quickstart를 사용해 기본 셋팅을 하자.

$ sphinx-quickstart
> Root path for the documentation [.]:
> Separate source and build directories (y/n) [n]:
> Name prefix for templates and static dir [_]:
> Project name: TIL
> Author name(s): Yunseop Song
> Project version []: 1.0
> Project release [1.0]:
> Project language [en]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]: n

Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

그럼 여러 파일이 생겨서 다음과 같이 바뀐다.

.
├── Makefile
├── README.md
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── mysql
│   └── mysql.md
├── python
│   └── python.md
└── vim
    └── vim.md

이 상태에서 make html을 사용하면 _build 디렉토리에 문서 페이지가 생성된다.

$ make html
Running Sphinx v1.6.5
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

그리고 _build/html/index.html을 열면 다음처럼 깔끔한 페이지를 볼 수 있다.

하지만 이 상태라면 마크다운 문서는 보여지지 않는다.
Sphinx에서 마크다운을 사용하려면 문서에 나온대로 recommonmark라는 패키지를 사용해야한다.

일단 recommonmark를 설치하자.

$ pip install recommonmark

그리고 conf.py 파일을 수정하자.

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

그리고 Sphinx에서 바라보는 master_doc인 index.rst에 toctree를 추가해야한다.
index.rst에 toctree를 추가하는 이유는 Markdown에서 지원을 하지 않기 때문에 약간의 편법...(사실 어떻게 하는지 잘 모르겠다.)

.. toctree::
    :caption: TOC:
    :glob:
    :titlesonly:

    mysql/*
    python/*
    vim/*

이렇게 추가를 하고 다시 make html을 하면 TOC가 제대로 추가된 것을 확인할 수 있다.

배포를 해봅시다.

Sphinx를 사용해 TIL 페이지는 완성되었다.

이제 배포만 남았는데 어디로 어떻게 배포할 지를 결정해야 했는데 구글링을 해보던 중 아주아주 좋은 것을 발견했다.

travis-sphinx라는 것인데 내 고민을 한방에 해결해주었다.

travis-sphinx를 사용하면 나는 문서를 커밋해서 Push하면 Travis에서 Sphinx로 빌드해서 gh-pages 브랜치로 배포를 해줘서 Github 호스팅을 사용할 수 있다.

travis-sphinx 설치

우선 pip를 사용해 travis-sphinx를 설치합시다.

$ pip install travis-sphinx

.travis.yml

.travis.yml을 추가한다.

language: python - "2.7"

install:
    - sudo pip install -U -r requirements.txt

script:
    - travis-sphinx build -s . --nowarn

after_success:
    - travis-sphinx deploy

Github Access Token 추가

Access Token 페이지로 가서 Generate new token을 눌러 Travis에서 사용할 토큰을 생성하자.
권한은 public_repo만 줬다.

생성된 토큰을 복사해 두고 Travis에 설정을 합시다.

Travis Environment Variables 추가

Travis에 설정 페이지로 가서 Environment Variables를 GH_TOKEN 이름으로 토큰 값을 추가한다.

배포!

이제 master로 푸시하면 Travis에서 Sphinx로 빌드한 html 파일들을 gh-pages 브랜치로 푸시하게 된다.

그리고 테마는 Readthedocs를 사용해서 다음과 같이 TIL 페이지를 만들었다.

그렇지만

Sphinx에서 Markdown을 사용할 때 Github Flavor Markdown에서는 지원하는 Table을 지원하지 않는다.

eval_rst라는 기능을 사용해서 rst 문법으로 Table을 사용할 수 있겠지만 아직 그냥 냅뒀다. 아직 답을 못찾은 걸 수도 있지않을까 해서...

그래도

이 페이지를 만들고 더 자주 TIL을 쓰게 되는 것 같아 잘 해둔 것 같다.