Help
Sphinx
#
Find similar titles
- (rev. 4)
- Ji-hye Lee
Structured data
- Category
- Software
- Image
- URL
- http://sphinx-doc.org/
Table of Contents
Sphinx (파이썬 문서제작 도구) #
Sphinx는 파이썬 프로젝트를 위한 문서작성 도구로 만들어 졌고, 현재 C/C++도 지원하고 있다. 앞으로 다른 언어도 지원할 예정이라고 한다. Sphinx는 다음과 같은 특징을 가진다.
- Output formats: HTML, LaTex, ePub, Textinfo, manual pages, plain text 포맷지원
- Extensive cross-references: function, class, citations, glossary terms 등을 위한 시맨틱마크업과 자동링크 생성 지원
- Hierarchical structure: 문서 트리구조를 쉽게 정의 할 수 있음. (하위 자식트리와 부모에 자동링크)
- Automatic indices: 인덱스 자동생성
- Code handling: 코드 하이라이팅 (Pygments highlighter 이용)
- Entensions: code snippets 자동테스트 등 여러가지 확장기능 지원
- Contributed extensions: 다른유저들이 제공는 50개 이상의 확상기능 들
Sphinx를 통해 문서를 작성하기 위해서는 reStructuredText(이하 'reST')라고 하는 마크업 언어를 숙지 해야한다. reST로 작성한 문서의 이름은 '.rst' 로 끝난다. reST는 본래 파이썬 홈페이지(www.python.org)제작을 위해 만들어진 문서화 도구이며 현재는 많은 도구와 언어 등의 문서화에 사용하고 있다.
설치방법 #
파이썬2.6 이상이 기본으로 필요하고 Sphinx는 1) Git을 통해 다운로드를 받거나, 2)python pip를 이용할 수 있다.
#파이썬 pip 이용
pip install sphinx
또한, 운영체체가 데비안이나 우분투인 경우에는 apt-get 명령어를 통해서도 설치할 수 있다. 그 밖의 운영체제에서의 설치는 다음을 통해 확인 할 수 있다.
#데비안/우분투에서의 설치
apt-get install python-sphinx
Sphinx 시작하기 #
기본구조 생성 #
sphinx를 설치한 후 명령어 sphinx-quickstart를 입력하면 자동으로 소스디렉토리와 기본파일들을 만들어준다.
#기본디렉토리 구조
/root(source directory)
/build
... (생략)
/source
index.rst
... (생략)
make.bat
Makefile
index.rst에 toctree 만들기 #
sphinx-quickstart를 통해 생성된 파일 중 source/index.rst는 document의 첫페이지가 된다. 아래와 같이 toctree를 이용해서 목차를 만들 수 있다. 목차에 입력한 'intro'와 'installation'은 index.rst와 같은 경로에 있는 'intro.rst', 'index.rst'를 자동으로 찾아서 목차로 만들어 준다.
#index.rst 예제
My documentation
================
Content:
.. toctree::
:maxdepth: 2
intro #intro.rst에 자동링크를 생성하고 목차에서 intro의 목차를 트리구조로 보여준다.
installation
Indices and tables
==================
* :ref: `genindex`
* :ref: `modindex`
* :ref: `search`
intro, installation 페이지 만들기 #
index.rst에 정의한 intro.rst와 installation.rst를 'source/'안에 만든다. 만들어진 rst파일은 index의 'instro'와 'installation'에 자동으로 링크된다.
/root
source/
index.rst
installation.rst #생성
intro.rst #생성
build/
...
HTML문서 building 하기 #
명령어 make html를 입력하면 rst문서로부터 생성된 HTML파일들이 build/디렉토리안에 생성된다.
/root
source/
...
build/
/html
intro.html
installation.html
intro.html
_source/
_static/
생성된 index.html을 웹브라우저로 열어서 생성된 문서를 확인한다.
Autodoc 사용하기 #
Sphinx는 파이썬 소스코드로부터 자동으로 문서를 생성해 주는 'Autodoc'을 제공한다.
conf.py 세팅 #
autodoc을 사용하기 위해서는 conf.py의 'extensions' 부분에 반드시 아래와 같이 autodoc이 추가되어 있어야 한다.
... (생략) ...
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
]
... (생략) ...
그리고, 파이썬 코드가 있는 path도 sys.path에 들어있어야 하므로 conf.py에 추가한다. path는 반드시 절대경로로 들어있어야 하므로 상대경로 일 경우 os.path.abspath를 이용해 절대경로로 바꿔서 설정한다.
... (생략) ...
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../..'))
modules/ 생성 #
source/ 디렉토리 안에 module/ 라는 이름의 디렉토리를 생성하고 원하는 이름으로 rst파일을 생성하고 아래와 같이 입력한다.
$ vim source/modules/module_a.rst
========
Module A
========
.. automodule:: [모듈명]
:members:
:undoc-members:
:inherited-members:
make html을 해주면 자동으로 입력한 모듈에 대한 문서가 생성되고, index의 '모듈목록'에서 확인 할 수 있다.
문서 테마 변경 #
source/conf.py의 'html_theme'에 원하는 테마를 입력한 후 make html을 실행하면 자동으로 css를 받아오고 html을 생성해준다.
참고 #
- Sphinx
- reST
