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('..'))

기본 구조

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

Read the docs 테마

• 설치

conda install sphinx_rtd_theme

• 설정

# conf.py 수정 
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]

# conf.py 수정 
html_logo = 'figs/logo.png'
latex_logo = 'figs/logo.png'

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

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',
}

• 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

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

1. 하나
2. 둘
 
 
- 하나
- 둘
   - 둘.하나
   - 둘.둘
- 셋

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

심볼 참조

:ref:`ref_symbol` 는 어쩌고 .. 

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

인라인 수식

:math:`e = mc^2`

수식 블럭

 .. math::
   :label: eval_func
 
   v = \frac{{score}_{my}}{{score}_{my} + {score}_{opponent}}

본문 내용중에 [#]_ 또는 [#something]_ 을 삽입
 
본문 내용 끝에 삽입
 
.. rubric:: Footnotes
.. [#] 풋노트 1
.. [#something] 풋노트 2
 
----
 
 
citation은 footnote와 유사하지만, global하게 사용
 
[Ref]_ , [ABC112]_
 
.. [Ref] Reference
.. [ABC112] Abc 112

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

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

- 기존 코드 삽입

.. _ref_symbol:
.. literalinclude:: ../scripts/example.py
   :linenos:
   :lines: 7-25
   :caption: example

.. literalinclude:: example.py
   :pyobject: Timer.start

.. literalinclude:: example.py
   :diff: example.py.orig

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

- StarCraft 2 API(`s2client-api`_)의 python wrapper
 
.. _s2client-api: https://github.com/Blizzard/s2client-api

# :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`

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

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, 이전 상태를 저장하고 있는 노드
  """
 

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

.. TODO::
   - todo 내용
 
.. note::
   - note 내용
 
.. warning::
   - warning 내용
 
.. seealso::
   - 더보기

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

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

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

tabulate

# 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
# =====  ======  =============