Sphinx

Overview

Sphinx 사용 법 정리.

Installation

debian/ubuntu 기준. <source lang=bash> $ sudo apt-get install python-sphinx </source>

sphinx-quickstart

sphinx 를 이용해서 처음 프로젝트를 생성할 때 사용하는 툴이다.

$ sphinx-quickstart 
Welcome to the Sphinx 1.4.4 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: /tmp/sphinx_simple

...
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

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, _]

Index-generating markup

인덱스 생성과 관련된 지시어.

• single

Creates a single index entry. Can be made a subentry by separating the subentry text with a semicolon (this notation is also used below to describe what entries are created).

• pair

pair: loop; statement is a shortcut that creates two index entries, namely loop; statement and statement; loop.

• triple

Likewise, triple: module; search; path is a shortcut that creates three index entries, which are module; search path, search; path, module and path; module search.

• see

see: entry; other creates an index entry that refers from entry to other.

• seealso

Like see, but inserts “see also” instead of “see”.

• module, keyword, operator, object, exception, statement, builtin

These all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module. (These are Python-specific and therefore deprecated.)

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

The execution context
---------------------

.. index:: offline, online, away, dnd_external, dnd, ringing, busy

.. tabularcolumns:: |l|L|
.. table:: User status

...

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`

Make options

다음의 옵션들을 제공한다.

$ make help
Please use `make <target>' where <target> is one of
  html       to make standalone HTML files
  dirhtml    to make HTML files named index.html in directories
  singlehtml to make a single large HTML file
  pickle     to make pickle files
  json       to make JSON files
  htmlhelp   to make HTML files and a HTML help project
  qthelp     to make HTML files and a qthelp project
  devhelp    to make HTML files and a Devhelp project
  epub       to make an epub
  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf   to make LaTeX files and run them through pdflatex
  text       to make text files
  man        to make manual pages
  texinfo    to make Texinfo files
  info       to make Texinfo files and run them through makeinfo
  gettext    to make PO message catalogs
  changes    to make an overview of all changed/added/deprecated items
  linkcheck  to check all external links for integrity
  doctest    to run all doctests embedded in the documentation (if enabled)

html

웹 페이지를 생성한다. 가장 쉽고, 간단하게 사용할 수 있다.

latexpdf

PDF 문서를 생성한다. 문법검사가 굉장히 까다롭다.

plugin - httpdomain

HTTP 관련 매뉴얼 작성시에 편리한 플러그인.

• https://pythonhosted.org/sphinxcontrib-httpdomain/

Directives

.. http:options:: path
Describes a HTTP resource’s OPTIONS method. It can also be referred by http:options role.

.. http:head:: path
Describes a HTTP resource’s HEAD method. It can also be referred by http:head role.

.. http:post:: path
Describes a HTTP resource’s POST method. It can also be referred by http:post role.

.. http:get:: path
Describes a HTTP resource’s GET method. It can also be referred by http:get role.

.. http:put:: path
Describes a HTTP resource’s PUT method. It can also be referred by http:put role.

.. http:patch:: path
Describes a HTTP resource’s PATCH method. It can also be referred by http:patch role.

.. http:delete:: path
Describes a HTTP resource’s DELETE method. It can also be referred by http:delete role.

.. http:trace:: path
Describes a HTTP resource’s TRACE method. It can also be referred by http:trace role.

.. http:copy:: path
Describes a HTTP resource’s COPY method. It can also be referred by http:copy role.

New in version 1.3.0.

.. http:any:: path
Describes a HTTP resource’s which accepts requests with any method. Useful for cases when requested resource proxying the request to some other location keeping original request context. It can also be referred by http:any role.

New in version 1.3.0.

Basic usage

기본 사용 예제

.. http:get:: /users/(int:user_id)/posts/(tag)

   The posts tagged with `tag` that the user (`user_id`) wrote.

   **Example request**:

   .. sourcecode:: http

      GET /users/123/posts/web HTTP/1.1
      Host: example.com
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: text/javascript

      [
        {
          "post_id": 12345,
          "author_id": 123,
          "tags": ["server", "web"],
          "subject": "I tried Nginx"
        },
        {
          "post_id": 12346,
          "author_id": 123,
          "tags": ["html5", "standards", "web"],
          "subject": "We go to HTML 5"
        }
      ]

   :query sort: one of ``hit``, ``created-at``
   :query offset: offset number. default is 0
   :query limit: limit number. default is 30
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :statuscode 200: no error
   :statuscode 404: there's no user

다음과 같이 보여진다.

GET /users/(int: user_id)/posts/(tag)
The posts tagged with tag that the user (user_id) wrote.

Example request:

GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

[
  {
    "post_id": 12345,
    "author_id": 123,
    "tags": ["server", "web"],
    "subject": "I tried Nginx"
  },
  {
    "post_id": 12346,
    "author_id": 123,
    "tags": ["html5", "standards", "web"],
    "subject": "We go to HTML 5"
  }
]
Query Parameters:
 	
sort – one of hit, created-at
offset – offset number. default is 0
limit – limit number. default is 30
Request Headers:
 	
Accept – the response content type depends on Accept header
Authorization – optional OAuth token to authenticate
Response Headers:
 	
Content-Type – this depends on Accept header of request
Status Codes:	
200 OK – no error
404 Not Found – there’s no user

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 />