Skip to content

Sphinx #

Find similar titles

3회 업데이트 됨.

Edit
  • 최초 작성자
    yeye
  • 최근 업데이트
    Ji-hye Lee

Structured data

Category
Software
Image
URL

Sphinx (파이썬 문서제작 도구) #

Sphinx는 파이썬 프로젝트를 위한 문서작성 도구로 만들어 졌고, 현재 C/C++도 지원하고 있다. 앞으로 다른 언어도 지원할 예정이라고 한다. Sphinx는 다음과 같은 특징을 가진다.

  1. Output formats: HTML, LaTex, ePub, Textinfo, manual pages, plain text 포맷지원
  2. Extensive cross-references: function, class, citations, glossary terms 등을 위한 시맨틱마크업과 자동링크 생성 지원
  3. Hierarchical structure: 문서 트리구조를 쉽게 정의 할 수 있음. (하위 자식트리와 부모에 자동링크)
  4. Automatic indices: 인덱스 자동생성
  5. Code handling: 코드 하이라이팅 (Pygments highlighter 이용)
  6. Entensions: code snippets 자동테스트 등 여러가지 확장기능 지원
  7. 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을 생성해준다.

참고 #

Incoming Links #

Related Data Sciences #

Related Articles #

Suggested Pages #

0.0.1_20230725_7_v68