$ conda install sphinx_rtd_theme  # Anaconda 사용 시
$ pip3 install sphinx_rtd_theme  # Anaconda 미사용 시

extensions = ['myst_parser']
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

$ mkdir docs/source/A
$ cat "Hi" > docs/source/A/a1.md
$ cat "Bye" > docs/source/A/a2.md

.. toctree::
   :maxdepth: 2
   :caption: A:
   A/a1.md
   A/a2.md

Welcome to my_package's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Table of Contents

   my_package

import os
import sys
# sys.path.insert(0, os.path.abspath('.'))   # Default path
sys.path.insert(0, os.path.abspath('../..'))   # 필자의 path

project
├── test
│   ├── A
│   │   ├── __init__.py
│   │   └── a.py
│   ├── B
│   │   ├── __init__.py
│   │   └── b.py
│   └── __init__.py
└── doc
    ├── Makefile
    ├── build
    └── source
        ├── _static
        ├── _templates
        ├── conf.py
        └── index.rst

"""
====================================
 :mod:`a` 모듈 a
====================================
.. moduleauthor:: hooni <hooni@hoo.ni>
.. note:: LGPLv3
설명
=====
이 모듈은 문서화 테스트를 위한 모듈입니다.
Revision History
-------------------
 * [2021/04/23] - 모듈 작성
"""
class A:
    """문서화 테스트를 위한 임시 클래스
    """
    def __init__(self, a: int):
        """ 클래스 생성자
        :param a: 생성자 파라미터
        >>> a = A(10)
        """
        self.a = a
    def print_value(self):
        """ 멤버변수 a를 출력하는 메소드
        >>> A(10).print_value()
        10
        """
        print(self.a)

$ sphinx-apidoc -f -o docs/source test
> Creating file docs/source\test.rst.
> Creating file docs/source\test.A.rst.
> Creating file docs/source\test.B.rst.
> Creating file docs/source\modules.rst.

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   modules

RST
글자 표현
italic 체 - * 을 양옆으로 붙임.
*텍스트*
bold 체 - ** 을 양옆으로 붙임.
**텍스트**
섹션 헤더

주의 : 제목의 위/아래에 들어가는 문자의 개수는 제목내용과 같거나 많아야 한다.

# 잘못된 예
title
==

# 잘된 예
title
=====

title
=======

# RST                   # MarkDown

==============
Section Title           # Section Title
==============

--------------
Section Title           ## Section Title
--------------

Section Title           ### Section Title
=============

Section Title           #### Section Title
-------------

Section Title           ##### Section Title
\`````````````

Section Title           ###### Section Title
'''''''''''''

1. 목록입니다.
2. 목록입니다.
#. 목록입니다.

들여쓰기 없음 (1)
    네 칸을 띄고 쓰면 들여쓰기 (2)
        네 칸씩 들여쓰기 가능 (3)
    네 칸을 띄고 쓰면 들여쓰기 (2)
들여쓰기 없음 (1)

-a          옵션 a 설명
-b file     옵션 b 설명
--opt_a     옵션 opt_a 설명

.. code::

    print("hello, rst!")

# Sphinx Directive 문법시 `code-block` 추천
.. code-block::

    print("hello, sphinx!")

.. image:: 이미지 파일 경로
    :height: 250
    :width: 250
    :scale: 50
    :alt: 이미지 설명

.. |이모티콘| image:: 이모티콘경로

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

.. list-table::
   :header-rows: 1

   * - A
     - B
     - C
   * - data1
     - data2
     - data3

.. csv-table:: 테이블 타이틀 (없어도 됨)
   :header-rows: 1

   A, B, C
   data1, data2, data3

.. csv-table:: Table Title
   :file: CSV file path
   :widths: 30, 70
   :header-rows: 1
 

 

 
 

     (adsbygoogle = window.adsbygoogle || []).push({});

ABC

--------

DEF

1. 번호를 명시적으로 사용 [5]_

.. [5] 각주 5번에 대한 노트부분
   엔터를 해서 사용해도 결과는 한 줄

결과 부분-----
[5] 각주 5번에 대한 노트부분 엔터를 해서 사용해도 결과는 한 줄

2. 번호를 자동으로 매겨주는 각주 방법, [#]_ 과 [#]_

.. [#] 첫번째 각주
.. [#] 두번째 각주

결과 부분-----
[1] 첫번째 각주
[2] 두번째 각주

----

3. 이걸 [#third] 나 [#fourth] 처럼 명시적인 이름을 부여할 수 있음
   결과는 위에 [#] 과 동일하게 번호를 순차적으로 매겨줌

.. [#third] 세번째 각주
.. [#fourth] 네번째 각주

결과 부분-----
[3] 세번째 각주
[4] 네번째 각주
4. Auto-symbol 각주 방법, 각주의 심볼이 숫자가 아닐 수 있음 [*]_ 과 [*]_

.. [*] 첫번째
.. [*] 두번째

결과 부분-----
[*]    첫번째
[†]    두번째
인용구
인용구는 대괄호와 _로 구성, [인용구]_

.. [인용구] 인용문구 예시입니다.

결과 부분-----
[인용구] 인용문구 예시입니다.

Title 라인
=========
이것은 `Title 라인`_ 을 하이퍼링크 하는방법 입니다.
Sphinx
toctree

.. toctree::
   :maxdepth: 2
   :glob:

   directory1/directory2/*
   directory1/directory3/*

sphinx-doc: The TOC tree (https://www.sphinx-doc.org/en/1.5/markup/toctree.html)

reStructuredText 문서 : http://docutils.sourceforge.net/docs/user/rst/quickref.html#substitution-references-and-definitions 
sphinx-doc: The TOC tree : https://www.sphinx-doc.org/en/1.5/markup/toctree.html
Sphinx and RST syntax guide : https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
한국어로 rst 문법 간략히 정리한 페이지 : http://www.incodom.kr/reStructuredText

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 [.]: docs/
위와 같이 물어봅니다. root 경로 설정입니다. 기본은 현재 폴더입니다.You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: 
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: my_package
> Author name(s): kei
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version []: 1.0
> Project release [1.0]:
문서 버전과 릴리즈 버전 정보 입력.If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]:
문서의 언어지원 입력. 기본은 영어.한국어를 원할 경우 ko를 입력한다.그러나 여기서는 테스트니까 default값으로 하자.The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:
파일 포멧 설정 기본 rst확장자를 사용.One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

Creating file docs/conf.py.
Creating file docs/index.rst.
Creating file docs/Makefile.
Creating file docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file docs/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

vi conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

$ make.dat html

.. toctree::
   :maxdepth: 2
   :caption: Table of Contents

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. toctree::
   :maxdepth: 2
   :caption: Table of Contents

   my_package

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. automodule:: my_package
   :members:
   :undoc-members:
   :show-inheritance:

   Modules

   -------

   .. automodule:: my_package.my_module
       :members:

    My Module
    ~~~~~~~~~

class Test(object):
    """두 개의 int 값을 입력받아 다양한 연산을 할 수 있도록 하는 클래스.

    :param int a: a 값
    :param int b: b 값
    """

    def __init__(self, a, b):
        self._a = a
        self._b = b

    def is_same(self):
        """미리 입력받은 a와 b값이 같은지 확인하여 결과를 반환합니다.

        :return: boolean True or False에 대한 결과, a와 b가 값으면 True, 다르면 False

        예제:
            다음과 같이 사용하세요:

            >>> Test(1, 2).is_same()
            False

        """
        return self._a == self._b

    def plus(self):
        """미리 입력받은 a와 b값을 더한 결과를 반환합니다.

        :returns: int a + b에 대한 결과

        예제:
            다음과 같이 사용하세요:

            >>> Test(2, 1).plus()
            3


        """
        return self._a + self._b

$ make html

$ make.dat html

출처: https://kshyun87.tistory.com/63 [Coding is 취미:티스토리]

def sum(arg1: int, arg2: int) -> int:
    """
    This is sum function.
    
    :param int arg1: Description of arg1.
    :param int arg2: Description of arg2.
    :return: Description of return value.
    :rtype: int
    
    :example:
    
    >>> a=1
    >>> b=2
    >>> sum(a, b)
   	3
    """
    return a + b

> param 섹션
인자의 이름, 데이터형, 인자의 설명을 기재합니다.
:param 타입 인수명: 인수의 설명
> return 섹션
return문을 사용한 함수의 리턴 값을 기재합니다.
:return: 리턴 값에 대한 설명
> rtype 섹션
return값에 대한 데이터형을 기재합니다.
:rtype: 데이터형
> example 섹션
본 함수에 대한 사용법을 기재합니다.

:example:
    >>> a = 1
    >>> b = 2
    >>> sum(a, b)
        3

def sum(arg1: int, arg2: int) -> int:
    """
    This is sum function.
    
    Args:
    	arg1 (int): Description of arg1.
    	arg2 (int): Description of arg2.
        
    Returns:
    	int: Description of return value
    
    Examples:
        
    >>> a=1
    >>> b=2
    >>> sum(a, b)
   	3
    """
    return a + b

> Args 섹션
인자의 이름, 데이터형, 인자의 설명을 기재합니다.

optional 한 경우, 데이터형 뒤에 "optional" 로 추가하면 됩니다.

Args:
    인자명 (인자의 데이터형): 인자 설명
    인자명 (인자의 데이터형, optional): 인자 설명
> Returns 섹션
return문을 사용한 함수의 리턴 값을 기재합니다.
reStructuredText와는 달리 rtype을 포함합니다.
Returns:
    리턴 값의 데이터형: 리턴 값의 설명
> Examples 섹션

Examples:
    함수의 사용법 기재
    
    >>> a = 1
    >>> b = 2
    >>> sum(a, b)
        3

pip install sphinx

mkdir docs
cd docs
sphinx-quickstart 	# Sphinx 설치
Welcome to the Sphinx 4.4.0 quickstart utility.

Please enter values for the following settings (just press Enter to       
accept a default value, if one is given in brackets).                     
                                                                          
Selected root path: .                                                     
                                                                          
You have two options for placing the build directory for Sphinx output.   
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.

> Separate source and build directories (y/n) [n]

The project name will occur in several places in the built documentation.
> Project name:
> Author name(s):
> Project release []: 

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: 

Creating file {PROJECT_PATH}/docs/source/conf.py.
Creating file {PROJECT_PATH}/docs/source/index.rst.
Creating file {PROJECT_PATH}/docs/Makefile.
Creating file {PROJECT_PATH}/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file {PROJECT_PATH}\docs\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

> Separate source and build directories : source 디렉토리와 build 디렉토리 분리 여부

문서화할게 많으면 source 디렉토리와 build 디렉토리를 분리하는게 좋음 (y)

> Project name : 문서에 출력될 프로젝트 명
> Author name(s) : 저자
> Project release: 프로젝트 버전 (시작인 경우, 1.0)
> Project language: Sphinx 에서 자동 생성되는 문서가 어떤 언어로 작성될지 선택

디폴트가 영어 (영어로 진행할거면 그냥 Enter)

출처: https://seulkom.tistory.com/entry/Python-문서화-1-Sphinx-설치-및-docstring-스타일-선택 [seulkom note:티스토리]

Example Google Style Python Docstrings
See also

Example NumPy Style Python Docstrings

Download: example_google.py

# -*- coding: utf-8 -*-
"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:
   http://google.github.io/styleguide/pyguide.html

"""

module_level_variable1 = 12345

module_level_variable2 = 98765
"""int: Module level variable documented inline.

The docstring may span multiple lines. The type may optionally be specified
on the first line, separated by a colon.
"""


def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """


def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """


def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the ``Args`` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

    If \*args or \*\*kwargs are accepted,
    they should be listed as ``*args`` and ``**kwargs``.

    The format for a parameter is::

        name (type): description
            The description may span multiple lines. Following
            lines should be indented. The "(type)" is optional.

            Multiple paragraphs are supported in parameter
            descriptions.

    Args:
        param1 (int): The first parameter.
        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

    Returns:
        bool: True if successful, False otherwise.

        The return type is optional and may be specified at the beginning of
        the ``Returns`` section followed by a colon.

        The ``Returns`` section may span multiple lines and paragraphs.
        Following lines should be indented to match the first line.

        The ``Returns`` section supports any reStructuredText formatting,
        including literal blocks::

            {
                'param1': param1,
                'param2': param2
            }

    Raises:
        AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
        ValueError: If `param2` is equal to `param1`.

    """
    if param1 == param2:
        raise ValueError('param1 may not be equal to param2')
    return True


def example_generator(n):
    """Generators have a ``Yields`` section instead of a ``Returns`` section.

    Args:
        n (int): The upper limit of the range to generate, from 0 to `n` - 1.

    Yields:
        int: The next number in the range of 0 to `n` - 1.

    Examples:
        Examples should be written in doctest format, and should illustrate how
        to use the function.

        >>> print([i for i in example_generator(4)])
        [0, 1, 2, 3]

    """
    for i in range(n):
        yield i


class ExampleError(Exception):
    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

    Note:
        Do not include the `self` parameter in the ``Args`` section.

    Args:
        msg (str): Human readable string describing the exception.
        code (:obj:`int`, optional): Error code.

    Attributes:
        msg (str): Human readable string describing the exception.
        code (int): Exception error code.

    """

    def __init__(self, msg, code):
        self.msg = msg
        self.code = code


class ExampleClass(object):
    """The summary line for a class docstring should fit on one line.

    If the class has public attributes, they may be documented here
    in an ``Attributes`` section and follow the same formatting as a
    function's ``Args`` section. Alternatively, attributes may be documented
    inline with the attribute's declaration (see __init__ method below).

    Properties created with the ``@property`` decorator should be documented
    in the property's getter method.

    Attributes:
        attr1 (str): Description of `attr1`.
        attr2 (:obj:`int`, optional): Description of `attr2`.

    """

    def __init__(self, param1, param2, param3):
        """Example of docstring on the __init__ method.

        The __init__ method may be documented in either the class level
        docstring, or as a docstring on the __init__ method itself.

        Either form is acceptable, but the two should not be mixed. Choose one
        convention to document the __init__ method and be consistent with it.

        Note:
            Do not include the `self` parameter in the ``Args`` section.

        Args:
            param1 (str): Description of `param1`.
            param2 (:obj:`int`, optional): Description of `param2`. Multiple
                lines are supported.
            param3 (:obj:`list` of :obj:`str`): Description of `param3`.

        """
        self.attr1 = param1
        self.attr2 = param2
        self.attr3 = param3  #: Doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr4 = ['attr4']

        self.attr5 = None
        """str: Docstring *after* attribute, with type specified."""

    @property
    def readonly_property(self):
        """str: Properties should be documented in their getter method."""
        return 'readonly_property'

    @property
    def readwrite_property(self):
        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
        should only be documented in their getter method.

        If the setter method contains notable behavior, it should be
        mentioned here.
        """
        return ['readwrite_property']

    @readwrite_property.setter
    def readwrite_property(self, value):
        value

    def example_method(self, param1, param2):
        """Class methods are similar to regular functions.

        Note:
            Do not include the `self` parameter in the ``Args`` section.

        Args:
            param1: The first parameter.
            param2: The second parameter.

        Returns:
            True if successful, False otherwise.

        """
        return True

    def __special__(self):
        """By default special members with docstrings are not included.

        Special members are any methods or attributes that start with and
        end with a double underscore. Any special member with a docstring
        will be included in the output, if
        ``napoleon_include_special_with_doc`` is set to True.

        This behavior can be enabled by changing the following setting in
        Sphinx's conf.py::

            napoleon_include_special_with_doc = True

        """
        pass

    def __special_without_docstring__(self):
        pass

    def _private(self):
        """By default private members are not included.

        Private members are any methods or attributes that start with an
        underscore and are *not* special. By default they are not included
        in the output.

        This behavior can be changed such that private members *are* included
        by changing the following setting in Sphinx's conf.py::

            napoleon_include_private_with_doc = True

        """
        pass

    def _private_without_docstring(self):
        pass

def multiply(a, b):  
"""  
입력받은 두 수를 곱한 결과를 반환하는 함수입니다.

매개변수:
a (int): 곱셈의 첫 번째 피연산자
b (int): 곱셈의 두 번째 피연산자

반환값:
int: 두 수를 곱한 결과
"""
	return a * b

result = multiply(3, 5)  
print(result) # Output: 15

$ pip install sphinx

"""  
math\_utils.py

수학 계산을 위한 유틸리티 함수들을 포함하는 모듈입니다.  
"""

def add(a, b):  
"""  
두 수를 더한 결과를 반환하는 함수입니다.

Parameters
----------
a : int or float
    덧셈의 첫 번째 피연산자
b : int or float
    덧셈의 두 번째 피연산자
	
Yields
------



Returns
-------
int or float
    두 수를 더한 결과
	
Raises
------
"""
return a + b

\=============  
제목  
\=============
소제목
문서 본문 내용...

$ make html 

주요 옵션

html_theme_options: HTML 출력 테마에 대한 설정을 담당하는 옵션이다. 예를 들어 다양한 테마 색상, 레이아웃 등을 변경할 수 있다.


exclude_patterns: 문서에서 제외할 파일 패턴을 지정하는 옵션이다. 예를 들어 특정 파일이나 폴더를 문서에 포함시키지 않을 때 사용한다.


master_doc: 기본 문서 파일을 지정하는 옵션이다. 기본적으로 index.rst 파일이 기본 문서 파일로 설정되어 있다.


extensions: 확장 모듈을 추가하고 사용하기 위해 설정하는 옵션이다. 예를 들어 코드 하이라이팅을 위한 sphinx.ext.highlight 모듈을 사용하려면 이 옵션을 추가한다.

html_theme_options = {
    'logo': 'logo.png',
    'color_scheme': 'light',
    'font_size': '16px',
    'sidebar_width': '300px'
}

exclude_patterns = [
    'private/*',
    'temp/*'
]

master_doc = 'main'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode'
]

----------------------------------------추가 -------------------------

테마(Theme) 변경: conf.py 파일에서 html_theme 옵션을 수정하여 문서의 테마를 변경할 수 있다.


레이아웃 수정: conf.py 파일에서 html_sidebars 옵션을 통해 사이드바의 레이아웃을 수정할 수 있다.


코드 하이라이팅: conf.py 파일에서 highlight_language 옵션을 통해 코드의 언어를 지정할 수 있다.

​* See: https://m.blog.naver.com/sooftware/221838103492

import torch.nn as nn

import torch.nn.functional as F

class ListenAttendSpell(nn.Module):

       """

       Listen, Attend and Spell (LAS) Model

​

       Args:

              - listener (nn.Module): encoder of seq2seq

              - speller (nn.Module): decoder of seq2seq

              - decode_function (nn.functional): A function used to generate symbols from RNN hidden state

​

       Reference:

              「Listen, Attend and Spell」 paper

              https://arxiv.org/abs/1508.01211

​

       How to Use:

              >>> listener = Listener(feat_size, 256, 0.5, 6, True, 'gru', True)

              >>> speller = Speller(vocab_size, 120, 8, 256 << (1 if use_bidirectional else 0))

              >>> model = ListenAttendSpell(listener, speller)

       """

       def __init__(self, listener, speller, decode_function = F.log_softmax, use_pyramidal = False):

              super(ListenAttendSpell, self).__init__()

              self.listener = listener

              self.speller = speller

              self.decode_function = decode_function

              self.use_pyramidal = use_pyramidal

​

       def forward(self, feats, targets=None, teacher_forcing_ratio=0.90, use_beam_search = False):

              listener_outputs, listener_hidden = self.listener(feats)

              y_hat, logit = self.speller(

                     inputs=targets,

                     listener_hidden=listener_hidden,

                     listener_outputs=listener_outputs,

                     function=self.decode_function,

                     teacher_forcing_ratio=teacher_forcing_ratio,

                     use_beam_search=use_beam_search

              )

              return y_hat, logit

$ pip install sphinx

$ pip install sphinx-rtd-theme

$ sphinx-quickstart 입력

import os
import sys
sys.path.append(os.path.abspath('.'))
sys.path.append(os.path.abspath('..'))
import sphinx_rtd_theme
project = 'Sphinx-Tutorial'
copyright = '2020, Sooftware'
author = 'Sooftware'
version = ''
release = '0.0'
extensions = [
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.napoleon',
    "sphinx_rtd_theme",
    'sphinx.ext.autodoc',
    'sphinx.ext.imgmath',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'recommonmark',
	'myst_parser'
]
templates_path = ['_templates']
source_suffix = [
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
]
master_doc = 'index'
language = None
exclude_patterns = []
pygments_style = 'sphinx'
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
htmlhelp_basename = 'Sphinx-Tutorialdoc'
latex_elements = {
}
latex_documents = [
    (master_doc, 'Sphinx-Tutorial.tex', 'Sphinx-Tutorial Documentation',
     'Sooftware', 'manual'),
]
man_pages = [
    (master_doc, 'sphinx-tutorial', 'Sphinx-Tutorial Documentation',
     [author], 1)
]
texinfo_documents = [
    (master_doc, 'Sphinx-Tutorial', 'Sphinx-Tutorial Documentation',
     author, 'Sphinx-Tutorial', 'One line description of project.',
     'Miscellaneous'),
]
epub_title = project
epub_exclude_files = ['search.html']
intersphinx_mapping = {'https://docs.python.org/': None}
todo_include_todos = True

.. Sphinx-Tutorial documentation master file, created by
   sphinx-quickstart on Thu Mar  5 04:08:37 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Sphinx-Tutorial's documentation!
===========================================

.. toctree::
   :maxdepth: 1
   :caption: Tutorial


   Tutorial

Tutorial
=====================================================

.. automodule:: src.tutorial
    :members:

$ make html 입력

$ make.bat html 입력

Sphinx-Tutorial

https://sh951011.github.io/Korean-Speech-Recognition/

 
Welcome to Korean Speech Recognition’s documentation! — Korean Speech Recognition 1.0 documentation
Welcome to Korean Speech Recognition’s documentation! Notes Introduction Preparation before Training More Details Architecture Models Package Reference Feature Dataset Loss Hparams

sh951011.github.io

def 함수명():

   ''' 내용 ''' → 주석안에 특정 규칙에 맞게 작성해둔 docstring을 파싱한다.

def convert_worksheet_to_df(workbook, sheet_name=['Sheet'], include_index=False, include_column=False):
    """ Excel 파일에서 원하는 Sheet를 지정해 list(Dataframe) 으로 반환

    Args:
        file_path (str): 저장할 대상 Excel Workbook
        sheet_name (list): Excel Workbook의 Sheet명
        include_index (bool, optional): index 포함여부
        include_column (bool, optional): column(header) 포함여부

    Returns:
        dict (sheet_name : pandas.DataFrame)
        
    Raises:
        ValueError: File path를 입력하지 않은 경우
        FileNotFoundError: File path의 경로에 파일 찾을 수 없는 경우

    """

sphinx install

pip install sphinx 수행

pip install sphinxcontrib-napoleon

Napoleon - Marching toward legible docstrings — napoleon 0.7 documentation

Separate source and build directories (y/n) [n]: n

docs
├── build
├── make.bat
├── Makefile
├── conf.py
├── index.rst
├── _static                            
└── _templates

my_pacakage
├── __init_.py
└── my_module.py

Separate source and build directories (y/n) [n]: y

source 폴더가 생성 된다. 관리 편의성을 위하여 특별한 사유 없으면 분리해서 사용하도록 하자 <-----

 

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static                            
   └── _templates
  
my_pacakage
├── __init_.py
└── my_module.py

 

build/

An empty directory (for now) that will hold the rendered documentation.

make.bat and Makefile

Convenience scripts to simplify some common Sphinx operations, such as rendering the content.

source/conf.py

A Python script holding the configuration of the Sphinx project. It contains the project name and release you specified to sphinx-quickstart, as well as some extra configuration keys.

source/index.rst

The root document of the project, which serves as welcome page and contains the root of the “table of contents tree” (or toctree).

Case 1

Separate source and build directories (y/n) [n]: n

C:\Users\pyexcel\docs>sphinx-quickstart
Welcome to the Sphinx 3.2.1 quickstart utility.

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

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n

The project name will occur in several places in the built documentation.
> Project name: pyexcel
> Author name(s): hoon
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ko

Creating file C:\Users\pyexcel\docs\conf.py.
Creating file C:\Users\pyexcel\docs\index.rst.
Creating file C:\Users\pyexcel\docs\Makefile.
Creating file C:\Users\pyexcel\docs\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file C:\Users\pyexcel\docs\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Case 2

Separate source and build directories (y/n) [n]: y

C:\Users\pyexcel\docs>sphinx-quickstart
Welcome to the Sphinx 3.2.1 quickstart utility.

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

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: pyexcel
> Author name(s): hoon
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ko

Creating file C:\Users\pyexcel\docs\source\conf.py.
Creating file C:\Users\pyexcel\docs\source\index.rst.
Creating file C:\Users\pyexcel\docs\Makefile.
Creating file C:\Users\pyexcel\docs\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file C:\Users\pyexcel\docs\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

... (생략) ...
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc','sphinx.ext.todo','sphinx.ext.napoleon'
]
todo_include_todos = True
... (생략) ...
sphinx.ext.napoleon : Google Style docstring 사용시 파싱을 해주는 extensions이다.
sphinx.ext.todo : Google Style docstring 사용시 Todo: 라고 적은 부분을 변환해줌. todo_include_todos=True값도 세트로 같이 설정해야 한다.
sphinx.ext.autodoc : 모듈을 자동으로 문서화해주는 extensions이다.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../..')) # docs/source/conf.py 인 경우
sys.path.insert(0, os.path.abspath('..'))    # docs/conf.py 인 경우
# 만약 경로 못찾는다 나오면 아래와 같이 풀경로 넣어야함
sys.path.insert(0, os.path.abspath('C:\\Users\\pyexcel\\my_package'))

My documentation
================

Content:

.. toctree::
    :maxdepth: 2

    my_package

Indices and tables
==================

* :ref: `genindex`
* :ref: `modindex`
* :ref: `search`

형식
sphinx-apidoc [ 옵션 ] -o < OUTPUT_PATH > < MODULE_PATH > [ EXCLUDE_PATTERN ...]

[옵션] -F : 이미 존재하는 .rst 파일들을 강제 overwrite (덮어쓰기) 하겠다는 옵션
-o OUTPUT_PATH : 생성된 소스가 있는 디렉토리입니다. 
MODULE_PATH : 문서화할 Python 패키지의 경로
EXCLUDE_PATTERN : 생성에서 제외될 fnmatch 스타일 파일 및/또는 디렉토리 패턴입니다.
--serperate : 각 모듈에 대한 문서를 자체 페이지에 넣습니다.
이 옵션을 주면 모듈 내 파일 마다 .rst 파일이 생성된다.
옵션 주지 않으면 모듈명.rst 하나에 전체 파일 정보가 들어간다.

결과 문서에 색인, 목차가 없음. 개체가 많으면 sphinx.ext.autosummary 사용하도록

sphinx-apidoc -F -o ./docs/source ./my_package

my_pacakge라는 이름의 모듈경로의 패키지를 자동 문서화하여 .rst 파일을 생성하고 docs 위치에 위치시킨다. 이미 같은 이름의 .rst 존재한다면 강제 덮어쓰기 한다.

C:\Users\pyexcel>sphinx-apidoc -F -o docs my_package/
Creating file ./docs/source\my_package.rst.
File C:\Users\pyexcel\docs\source\conf.py already exists, skipping.
File C:\Users\pyexcel\docs\source\index.rst already exists, skipping.
Creating file C:\Users\pyexcel\docs\source\Makefile.
Creating file C:\Users\pyexcel\docs\source\make.bat.

sphinx-apidoc -F -o ./docs/source ./my_package --separate

C:\Users\hoon\pyexcel>sphinx-apidoc -F -o docs my_package/ --separate
Creating file docs\my_package.rst.
Creating file docs\my_package.pandastool.rst.
Creating file docs\my_package.pyexceltool.rst.
Creating file docs\my_package.pywinexceltool.rst.
Creating file C:\Users\pyexcel\docs\conf.py.
Creating file C:\Users\pyexcel\docs\index.rst.
File C:\Users\pyexcel\docs\Makefile already exists, skipping.
File C:\Users\pyexcel\docs\make.bat already exists, skipping.

index.rst 의 doctree에 my_package가 추가되어 index.html 접속하면 my_package가 보인다.

Make html 수행

C:\Users\pyexcel>cd docs

C:\Users\pyexcel\docs>make html
Running Sphinx v3.2.1
loading translations [ko]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices...  genindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

docs\source_build\html\ 아래에 html 파일이 생성된다.
index.html 이 최상단 웹페이지다. 열어본다.

sphinx-build — Sphinx documentation

sphinx-build [options] <sourcedir> <outputdir> [filenames …]
sourcedir : conf.py 파일이 있는 상위 폴더를 넣어야 함
-b 옵션으로 는 다양한 형식의 문서를 생성 할 수 있습니다. (기본값은 HTML)
명령줄에서 빌더 이름을 지정하여 형식을 선택합니다. 빌더는 문서 처리와 관련된 다른 작업도 수행할 수 있습니다. 사용 가능한 빌더 목록은 를 참조하십시오 .

-b singlehtml : 하나의 html 파일로 빌드
예시

sphinx-build -b singlehtml ./docs/source ./docs/build

source/conf.py의 'html_theme'에 원하는 테마를 입력한 후 make html을 실행하면 자동으로 css를 받아오고 html을 생성해준다.

1. pip install sphinx-adc-theme

2. conf.py 파일에 아래 내용 추가

import sphinx_adc_theme
html_theme = 'sphinx_adc_theme'
html_theme_path = [sphinx_adc_theme.get_html_theme_path()]