[Sphinx] Describing code in Sphinx (Python) (1)

Describing code in Sphinx

 

Sphinx는 Python, C, C++, JavaScript 및 reStructuredText와 같은 여러 언어로 코드 개체 문서화를 지원한다. 각각은 도메인 별로 그룹화된 일련의 지시문 및 역할을 사용하여 문서화할 수 있다. 튜토리얼의 나머지 부분에서는 Python 도메인을 사용하지만 여기에서 볼 수 있는 모든 개념은 다른 도메인에도 적용된다.

 

Python 객체 문서화

 

Sphinx는 Python 도메인에서 함께 그룹화된 Python 객체를 문서화하기 위한 여러 역할과 지시문을 제공한다 . 예를 들어, py:function다음과 같이 지시문을 사용하여 Python 함수를 문서화할 수 있다.

 

Creating recipes
----------------

To retrieve a list of random ingredients,
you can use the ``lumache.get_random_ingredients()`` function:

.. py:function:: lumache.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
   :return: The ingredients list.
   :rtype: list[str]

 

다음과 같이 렌더링된다.

 

Sphinx는 지시문의 인수를 구문 분석하고 모듈, 함수 이름 및 매개 변수를 적절하게 강조 표시했다... py:function 지시문 내용에는 함수에 대한 한 줄 설명과 함수 매개변수, 예상 유형, 반환 값 및 반환 유형이 포함된 정보 필드 목록 이 포함된다.

 

Python 객체 상호 참조

 

기본적으로 이러한 지시문은 대부분 해당 역할을 사용하여 문서의 모든 부분에서 상호 참조할 수 있는 엔터티를 생성 한다. 함수의 경우 py:func다음과 같이 사용할 수 있다.

 

The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

 

코드 문서를 생성할 때 Sphinx는 명시적으로 역할을 사용할 필요 없이 개체 이름만 사용하여 자동으로 상호 참조를 생성한다. py:exception 예를 들어, 지시문 을 사용하여 함수에서 발생하는 사용자 정의 예외를 설명할 수 있다.

 

.. py:exception:: lumache.InvalidKindError

   Raised if the kind is invalid.

 

그런 다음 이 예외를 함수의 원래 설명에 추가한다.

 

.. py:function:: lumache.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]

 

마지막으로 결과는 다음과 같다.

 

 

문서에 doctest 포함

 

이제 Python 라이브러리의 코드를 설명하고 있으므로 문서와 코드를 가능한 한 동기화된 상태로 유지하는 것이 유용할 것이다. Sphinx에서 이를 수행하는 방법 중 하나 는 문서가 빌드될 때 실행되는 doctests 라는 문서에 코드 조각을 포함하는 것이다.

 

여기서 다루는 doctest 및 기타 Sphinx 기능을 시연하려면 Sphinx에서 코드를 가져올 수 있어야 한다. 이를 달성하려면 시작 부분에 conf.py 다음을 작성한다.

 

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here.
import pathlib
import sys
sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())

 

그런 다음 문서에 doctest를 추가하기 전에 다음에서 doctest 확장을 활성화한다 conf.py.

 

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

 

다음으로 doctest 블록을 다음과 같이 작성한다.

 

>>> import lumache
>>> lumache.get_random_ingredients()
['shells', 'gorgonzola', 'parsley']

 

Doctest에는 >>>표준 Python 인터프리터 프롬프트와 함께 실행될 Python 명령과 각 명령의 예상 출력이 포함된다. 이런 식으로 Sphinx는 실제 출력이 예상 출력과 일치하는지 확인할 수 있다.

 

doctest 실패가 어떻게 보이는지 관찰하기 위해 (위의 코드 오류가 아니라) 먼저 반환 값을 잘못 작성해본다. 따라서 다음 get_random_ingredients과 같은 기능을 추가한다.

 

def get_random_ingredients(kind=None):
    return ["eggs", "bacon", "spam"]

 

이제 문서의 doctest를 실행하기 위해 실행할 수 있다. 실제 코드가 지정된 대로 작동하지 않기 때문에 처음에는 오류가 표시된다 (make doctest).

 

(.venv) $ make doctest
Running Sphinx v4.2.0
loading pickled environment... done
...
running tests...

Document: usage
---------------
**********************************************************************
File "usage.rst", line 44, in default
Failed example:
    lumache.get_random_ingredients()
Expected:
    ['shells', 'gorgonzola', 'parsley']
Got:
    ['eggs', 'bacon', 'spam']
**********************************************************************
...
make: *** [Makefile:20: doctest] Error 1

 

doctest는 예상 결과와 실제 결과를 보고하여 쉽게 확인할 수 있다. 이제 기능을 수정할 시간이다.

 

def get_random_ingredients(kind=None):
    return ["shells", "gorgonzola", "parsley"]

 

그리고 마침내 성공을 보고한다.

 

그러나 대규모 프로젝트의 경우 이 수동 접근 방식이 다소 지루할 수 있다. 다음 섹션에서는 프로세스를 자동화하는 방법을 볼 것이다.

 

https://www.sphinx-doc.org/en/master/tutorial/describing-code.html#documenting-python-objects

Describing code in Sphinx — Sphinx documentation