====== Sphinx ======


===== Project API 문서 만들기 (Python) =====

Sphinx 설치 후 프로젝트 폴더에서 

  sphinx-apidoc -F -f -o docs .
  
docs/conf.py를 적당히 수정후 build

  docs/make html

  * 양식
    * https://www.python.org/dev/peps/pep-0257/
    * http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy
    * http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html


===== 에러 처리 =====

autodoc can't import/find module

  # conf.py
  sys.path.append('{PROJECT_DIR}')

  # {PROJECT_DIR}/docs 일 경우
  import os
  import sys
  sys.path.insert(0, os.path.abspath('..'))

===== index.rst ====

기본 구조
<code rst>
.. include:: ../README.rst


Tutorial
========

.. toctree::
   :maxdepth: 4

   Microchess AI 경진대회 <01-microchess_ai_competition.rst>
   Microchess AI 플랫폼 <02-microchess_ai_platform.rst>
   기본 AI 예제 <03-basic_ai_examples.rst>
   MCTS 예제 <04-mcts.rst>
   Self-Learning 예제 <05-self_learning.rst>


API
===

.. toctree::
   :maxdepth: 4

   scripts
   agents
      basic <agents.basic.rst>
      search <agents.search.rst>
      self_learning <agents.self_learning.rst>
      stockfish <agents.stockfish.rst>


* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
</code>

===== 테마 =====

Read the docs 테마

  * 설치
<code bash>
conda install sphinx_rtd_theme
</code>

  * 설정
<code python>
# conf.py 수정 
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
</code>

===== Logo =====

<code python>
# conf.py 수정 
html_logo = 'figs/logo.png'
latex_logo = 'figs/logo.png'
</code>


===== 확장 =====

<code python>
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.mathjax',  # 수식
    'sphinx.ext.githubpages',
]

</code>


===== latex ======

<code python>

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    'preamble': r'\usepackage{kotex}',  # 한글 사용

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}
</code>

===== 문법 =====

  * http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
  * https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html?highlight=ref#id16
  * https://pythonhosted.org/an_example_pypi_project/sphinx.html
==== head ====

<code rst>
.. module:: logging
   :synopsis: Flexible event logging system for applications.

.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
</code>

==== 불릿 포인트 ====

<code rst>

1. 하나
2. 둘


- 하나
- 둘
   - 둘.하나
   - 둘.둘
- 셋
</code>

==== 그림 ====

<code rst>

.. _ref_symbol:
.. figure:: figs/figure.png
    :figwidth: 200

    figure 이름

</code>

심볼 참조
<code rst>
:ref:`ref_symbol` 는 어쩌고 .. 
</code>

** :ref:`_ref_symbol` 는 어쩌고 ..  로 하면 안됨 **


==== 수식 ====

인라인 수식

<code rst>
:math:`e = mc^2`
</code>

수식 블럭

<code rst>
 .. math::
   :label: eval_func

   v = \frac{{score}_{my}}{{score}_{my} + {score}_{opponent}}
</code>



==== ref/footnote ====

<code rst>

본문 내용중에 [#]_ 또는 [#something]_ 을 삽입

본문 내용 끝에 삽입

.. rubric:: Footnotes
.. [#] 풋노트 1
.. [#something] 풋노트 2

----


citation은 footnote와 유사하지만, global하게 사용

[Ref]_ , [ABC112]_

.. [Ref] Reference
.. [ABC112] Abc 112

</code>


==== code block ====

- 문자열 앞에 공백 세개를 삽입하면 블럭이 됨
- 코드 블럭 삽입

<code rst>

.. code-block:: none
   :linenos:

   [2018-04-23 15:40:07,079 DEBUG] White
   [2018-04-23 15:40:07,079 DEBUG] Black


.. code-block:: python
   :linenos:

   def func(x):
       return x + 1

</code>

- 기존 코드 삽입

<code rst>
.. _ref_symbol:
.. literalinclude:: ../scripts/example.py
   :linenos:
   :lines: 7-25
   :caption: example
</code>

<code rst>
.. literalinclude:: example.py
   :pyobject: Timer.start
</code>

<code rst>
.. literalinclude:: example.py
   :diff: example.py.orig
</code>
==== 디렉토리 구조 ====

<code rst>
::

   root
    ├── A1
    ├── A2
    └── A3
        └── B1

</code>

==== 링크 ====

<code rst>
- StarCraft 2 API(`s2client-api`_)의 python wrapper

.. _s2client-api: https://github.com/Blizzard/s2client-api
</code>


===== 모듈/객체/함수/변수 참조 =====

<code rst>
# :source:`Lib/logging/__init__.py`
`scripts/0_setup_script_dev.sh <../../../scripts/0_setup_script_dev.sh>`_

:mod:`search`

# automodule

:class:`search.mcts`

# autoclass

:classmethod:`search.mcts.act`

:func:`search.search`

# autoclass

:data:`search.MAX_DEPTH`
</code>

  - python domain 참조
    - http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html


===== 함수 시그니처 =====

<code python>
from typing import List, Dict, Set, Tuple, Any, Optional, Union # mypy type checking

# 현재 네임스페이스에 없는 타입을 참조하려면
# def query_available_abilities(self, units: Union[List[Unit], "Units"], ignore_resource_requirements: bool=False) -> List[List[AbilityId]]:

def func(a: str, b: List[int], c: Union[int, float, str]) -> Optional[Union[int, float]]:
  """
  :param str a: a 설명
  :param List[int] b: b설명
  :param Union[int, float, str] c: c설명
  :return: 반환 값 d 설명
  :rtype: Optional[Union[int, float]] 
  
  """
  ...
  
  return d


class Node(object):
  """
  Node
  
  Attrs:
  
  - (bool) -- turn, white=True, black=False
  - (:class:`scripts.run_game.State`) -- state
  - (:class:`agents.self_learning.mcts.Node`) -- parent, 이전 상태를 저장하고 있는 노드
  """
  
</code>

  * Python Signatures 참조
    * http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html


===== 강조 블럭 =====

<code rst>
.. TODO::
   - todo 내용

.. note::
   - note 내용

.. warning::
   - warning 내용

.. seealso::
   - 더보기
</code>

===== 사이드바 =====

<code rst>
.. sidebar:: Important

   This page contains the API reference information. For tutorial
   information and discussion of more advanced topics, see

   * :ref:`Basic Tutorial <logging-basic-tutorial>`
   * :ref:`Advanced Tutorial <logging-advanced-tutorial>`
   * :ref:`Logging Cookbook <logging-cookbook>`
</code>

===== Table =====

<code rst>
.. list-table:: Title
   :widths: 25 25 50
   :header-rows: 1

   * - Heading row 1, column 1
     - Heading row 1, column 2
     - Heading row 1, column 3
   * - Row 1, column 1
     -
     - Row 1, column 3
   * - Row 2, column 1
     - Row 2, column 2
     - Row 2, column 3
</code>

  * https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html


**tabulate**

<code python>
# conda install tabulate

from tabulate import tabulate
table = [["Sun",696000,1989100000], ["Earth",6371,5973.6], ["Moon",1737,73.5], ["Mars",3390,641.85]]
print(tabulate(table, ["P", "L", "b"], 'rst'))

# =====  ======  =============
# P           L              b
# =====  ======  =============
# Sun    696000     1.9891e+09
# Earth    6371  5973.6
# Moon     1737    73.5
# Mars     3390   641.85
# =====  ======  =============
</code>