Sphinx

Overview

Sphinx 사용 법 정리.

paragraph-level markup

.. note::

.. note::

   This function is not suitable for sending spam e-mails.

.. versionadded::

.. versionadded:: 2.5
   The *spam* parameter.

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”.

Cross-referencing other items of interest

여기에 있는 markup 들은 cross-reference 로 생성될 수 있는 것들이다. 하지만 해당 object 를 직접 참조하지는 않는다.

:term:

glossary 항목의 term 을 가리킨다. glossary 는 glossary 지시어를 통해서 생성되며, 항목 혹은 용어들의 정의를 나타내는데 쓰인다. 반드시 같은 파일내에 정의되어야 하는 것은 아니다. 즉, glossary.rst 파일과 같이 따로 파일을 만들어도 참조가 가능하다. 만약 정의되어 있지 않은 term 을 사용시엔, 빌드시 경고 메시지나 나온다.

:term:`timestamp`

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

References

<references />