Sphinx – create documentation

//bitbucket.org/birkenfeld/sphinx/

via Overview — Sphinx 1.1.2 documentation.

Installation

tar xvzf Jinja2-2.6.tar.gz
cd Jinja2-2.6
python setup.py build
python setup.py install --prefix=/user/cychong/local

tar xvzf Pygments-1.4.tar.gz
cd Pygments-1.4
python setup.py build
python setup.py install --prefix=/user/cychong/local

tar xvzf Sphinx-1.1.2.tar.gz
cd Sphinx-1.1.2
python setup.py build
python setup.py install --prefix=/user/cychong/local

Tutorial
http://matplotlib.sourceforge.net/sampledoc/

http://www.ibm.com/developerworks/library/os-sphinx-documentation/

Syntax

http://sphinx.pocoo.org/rest.html
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

한글 인코딩

source/conf.py 파일에서 encoding과 language 지정

source_encoding = 'utf-8-sig'
language = 'ko'

Doxygen 연계해서 사용하기
* http://michaeljones.github.com/breathe/ 설치
* Doxyfile에 XML 생성 옵션 켜기

GENERATE_XML = YES

* conf.py에 정보 추가 – extension

extensions = ['sphinx.ext.pngmath', 'sphinx.ext.todo', 'breathe']

* conf.py에 doxygen의 정보 추가

breathe_projects = {
    "nutshell":"../examples/specific/nutshell/xml/",
    }

* Doxygen의 결과물을 이용하려면 다음 keyword를 사용할 것.

.. doxygenindex::
.. doxygenfunction::
.. doxygenstruct::
.. doxygenenum::
.. doxygentypedef::
.. doxygenclass::

function_A의 정의를 이용하려면 다음과 같이 rst 파일에 기술(참고)

.. doxygenfunction::function_A


하나 이상의 Doxygen 결과 이용하기

만일 하나 이상의 doxygen project를 이용해서 문서를 생성하는 경우 source/conf.py의 breathe_projects에 다음과 같이 설정한다.

breathe_projects = { 
    "Project A":  "/user/cychong/source_dir_1/xml", 
    "Project B":  "/user/cychong/source_dir_2/xml" 
}

그리고 rst 파일에서 default project가 아닌 다른 project의 심볼을 참조하는 경우 다음과 같이 project 정보를 명시한다.

.. doxygenfunction:: function_from_project_A
   :project: Project A
.. doxygendefine:: macro_from_project_B
   :project: Project B</code>

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s