[Sphinx] 코드에서 자동 문서 생성 (1)

코드에서 자동 문서 생성 (Automatic documentation generation from code)

 

Sphinx의 Python 함수를 수동으로 문서화했다. 그러나 기능 서명이 동일하지 않았기 때문에 설명은 코드 자체와 동기화되지 않았다. 게다가 재사용하면 좋을 문서의 Python 독스트링은 두 곳에 정보를 작성하지 않아도 된다.

 

다행히 autodoc 확장은 이 기능을 제공한다.

 

autodoc으로 서명 및 독스트링 재사용

 

autodoc을 사용하려면 먼저 활성화된 확장 목록에 autodoc을 추가한다.

 

다음으로 지시어의 내용을 다음과 같이 원본 Python 파일의 함수 docstring으로 이동한다 (py:function).

 

def get_random_ingredients(kind=None):
    """
    Return a list of random ingredients as strings.

    :param kind: Optional "kind" of ingredients.
    :type kind: list[str] or None
    :raise lumache.InvalidKindError: If the kind is invalid.
    :return: The ingredients list.
    :rtype: list[str]

    """
    return ["shells", "gorgonzola", "parsley"]

 

마지막으로 Sphinx 설명서의 지시문을 다음으로 교체합한다 (py:functionautofunction).

 

you can use the ``lumache.get_random_ingredients()`` function:

.. autofunction:: lumache.get_random_ingredients

 

이제 HTML 문서를 빌드하면 출력이 동일할 것이다. 코드 자체에서 생성된다는 장점이 있다. Sphinx는 독스트링에서 reStructuredText를 가져와 포함시켰고 적절한 상호 참조도 생성했다.

 

다른 개체에서 문서를 자동 생성할 수도 있다. 예를 들어, InvalidKindError예외에 대한 코드를 추가한다.

 

class InvalidKindError(Exception):
    """Raised if the kind is invalid."""
    pass

 

그리고 다음과 같이 지시문을 바꾼다 (py:exceptionautoexception).

 

or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

.. autoexception:: lumache.InvalidKindError

 

그리고 다시 실행 후 출력은 이전과 동일하다.

 

extensions = [ 'sphinx.ext.duration', 'sphinx.ext.doctest', 'sphinx.ext.autodoc', ]

 

https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html

Automatic documentation generation from code — Sphinx documentation