$ 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
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.
$ 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를 설치하자.
1
$ pip install recommonmark
그리고 conf.py 파일을 수정하자.
1 2 3 4 5 6 7
from recommonmark.parser import CommonMarkParser
source_parsers = { '.md': CommonMarkParser, }
source_suffix = ['.rst', '.md']
그리고 Sphinx에서 바라보는 master_doc인 index.rst에 toctree를 추가해야한다. index.rst에 toctree를 추가하는 이유는 Markdown에서 지원을 하지 않기 때문에 약간의 편법…(사실 어떻게 하는지 잘 모르겠다.)
1 2 3 4 5 6 7 8
.. toctree:: :caption: TOC: :glob: :titlesonly:
mysql/* python/* vim/*
이렇게 추가를 하고 다시 make html을 하면 TOC가 제대로 추가된 것을 확인할 수 있다.
배포를 해봅시다.
Sphinx를 사용해 TIL 페이지는 완성되었다.
이제 배포만 남았는데 어디로 어떻게 배포할 지를 결정해야 했는데 구글링을 해보던 중 아주아주 좋은 것을 발견했다.
