Sphinx

Overview

Sphinx 사용 법 정리.

Miscellaneous markup

다음의 추가적인 Markup 을 사용 할 수 있다.

Tables

Table 항목에 다음의 속성 항목들을 사용할 수 있다.

tabularcolumns

테이블의 칼럼 속성을 지시할 수 있다. LaTex tabulary package 의 인자값으로 사용된다.

 .. tabularcolumns:: column spec

column spec 값으로는 다음의 값들이 사용 가능하다. Sphinx 에서는 기본값으로 모든 column 에 L 값을 지정한다.

• L flush left column with automatic width
• R flush right column with automatic width
• C centered column with automatic width
• J justified column with automatic width

다음과 같이 사용된다.

.. tabularcolumns:: |r|l|

Including content based on tags

특정 Tag 가 지정될 때에만 항목을 참조하도록 만들 수 있다.

.. only:: <expression>

만약 반드시 두 개 이상의 tag 가 반드시 설정되어야만 허용되도록 하고 싶다면 다음과 같이 하면 된다. tag 지정시 -t 옵션을 사용하거나 conf.py 파일에 설정하면된다.

.. only:: html and draft

다음의 캐릭터들들만 tag 에 사용할 수 있다. [a-z, A-Z, 0-9, _]

Inline markup

Cross-referencing sytax

:ref:

문서 내에 정의한 참조로의 링크를 건다.

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

.. figure 지시어에도 사용할 수 있다.

.. _my-figure:

.. figure:: whatever

   Figure caption

a reference :ref:`my-figure` would insert a reference to the figure with link text “Figure caption”.

Errors

latexpdf long line break

make latexpdf 로 pdf 생성시 quote 부분에 긴 문장이 있는 경우, pdf 에서 깨져서 보이는 현상이 있다. 이는 sphinx 의 버그이며 sphinx-1.4.2 버전에서 패치가 되었다<ref>http://www.sphinx-doc.org/en/stable/changes.html#release-1-4-2-released-may-29-2016</ref>. 즉, sphinx-1.4.2 이전 버전에서는 이를 해결할 방법이 없으며 문제가 발생하는 Quote 를 하나하나 수작업으로 맞추는 수 밖에 없다.

#2304: auto line breaks in latexpdf codeblocks
#1534: Word wrap long lines in Latex verbatim blocks

*.sty not found

make latexpdf 명령어로 pdf 문서 를 만들 때, 다음과 다음과 같은 에러를 만나는 경우가 있다. 단순히 패키지 미설치로 인한 오류이며 해당 패키지를 설치해주면 문제는 해결된다.

! LaTeX Error: File `cmap.sty' not found.

! Font T1/cmr/m/n/10=ecrm1000 at 10.0pt not loadable: Metric (TFM) file not found.

! LaTeX Error: File `titlesec.sty' not found.

다음의 명령어를 실행하면 된다. <source lang=bash> $ sudo apt-get install texlive-latex-extra $ sudo apt-get install texlive-latex-recommended $ sudo apt-get install texlive-fonts-recommended </source>

See also

• http://www.sphinx-doc.org/en/stable/rest.html - reStructuredText Primer
• http://www.sphinx-doc.org/en/stable/markup/misc.html - Miscellaneous markup