문서 작성

시작하기

일반 파일 구조

모든 문서는 doc/. 이 doc/ 디렉토리에는 설명서 페이지에 렌더링되는 Sphinx 및 reStructuredText( ReST ; ) 파일에 대한 구성 파일이 포함되어 있습니다..rst

문서는 세 가지 방법으로 작성됩니다. 먼저 API 문서( )는 Matplotlib 라이브러리에 있는 클래스의 독스트링에서 Sphinxdoc/api 에 의해 생성됩니다 . 를 제외하고 의 파일 은 문서가 빌드될 때 생성됩니다. 아래의 docstring 작성을 참조 하십시오 .doc/api/api_changes/.rstdoc/api

둘째, , 및 의 콘텐츠는 , 및 doc/plot_types의 doc/galleryPython 파일에서 Sphinx Gallerydoc/tutorials 에 의해 생성됩니다 . 이러한 소스 는 주석에 ReST 문서가 내장된 Python 스크립트로 구성됩니다. 아래 의 예시 및 자습서 작성을 참조 하세요.plot_types/examples/tutorials/

셋째, Matplotlib 의 하위 디렉토리 에 ReST 로 작성된 내러티브 문서가 doc/users/있습니다. 갤러리나 튜토리얼 예제가 아닌 파일 에 적합한 새 문서를 추가 .rst하려면 적절한 하위 디렉토리를 선택하여 해당 하위 디렉토리의 목차에 파일을 추가하십시오 index.rst. 아래의 ReST 페이지 작성을 참조하십시오 .

메모

, , , 및 ( 제외 )의 .rst파일을 직접 편집하지 마십시오 . Sphinx 는 문서를 작성할 때 이러한 디렉토리에서 파일을 재생성합니다.doc/plot_typesdoc/gallerydoc/tutorialsdoc/apidoc/api/api_changes/

문서 빌드 설정

Matplotlib에 대한 문서는 Sphinx 문서 생성 도구 를 사용하여 reStructuredText( ReST ) 에서 생성됩니다.

문서를 작성하려면 개발을 위해 Matplotlib를 설정 해야 합니다 . 특히 문서를 작성하는 데 필요한 추가 종속성 에 유의하십시오.

문서 작성

문서 소스는 doc/트렁크의 디렉토리에서 찾을 수 있습니다. Sphinx의 구성 파일은 doc/conf.py. Sphinx가 구문 분석하는 디렉토리, 문서 작성 방법 및 확장 사용 방법을 제어합니다. 문서를 html 형식으로 빌드하려면 다음을 입력 doc/하고 실행하십시오.

make html

다른 유용한 호출에는 다음이 포함됩니다.

# Delete built files.  May help if you get errors about missing paths or
# broken links.
make clean

# Build pdf docs.
make latexpdf

이 SPHINXOPTS변수는 기본적으로 전체 문서를 빌드하도록 설정되지만 경고가 있는 경우 종료 상태 1로 종료됩니다. 설정을 해제하려면 다음을 사용하십시오.-W --keep-going

make SPHINXOPTS= html

O변수를 사용하여 추가 옵션을 설정할 수 있습니다.

• make O=-j4 html4개의 프로세스로 병렬 빌드를 실행합니다.

• make O=-Dplot_formats=png:100 html낮은 해상도로 수치를 저장합니다.

• make O=-Dplot_gallery=0 html갤러리 빌드를 건너뜁니다.

여러 옵션을 결합할 수 있습니다(예: .make O='-j4 -Dplot_gallery=0' html

Windows에서는 다음과 같이 옵션을 환경 변수로 설정합니다.

set SPHINXOPTS= & set O=-j4 -Dplot_gallery=0 & make html

로컬로 빌드된 문서 표시 중

빌드된 문서는 폴더에서 사용할 수 있습니다 build/html. 기본 브라우저에서 열 수 있는 단축키는 다음과 같습니다.

make show

ReST 페이지 쓰기

대부분의 문서는 개별 클래스 및 메서드의 독스트링, 명시적 .rst파일 또는 예제 및 자습서에 있습니다. 이들 모두는 ReST 구문을 사용하며 Sphinx 에 의해 처리됩니다 .

Sphinx reStructuredText Primer 는 ReST 사용에 대한 좋은 소개입니다. 자세한 정보는 reStructuredText 참조 문서 에서 확인할 수 있습니다 .

이 섹션에는 Matplotlib 설명서에서 ReST가 사용되는 방식에 대한 추가 정보 및 규칙이 포함되어 있습니다.

서식 및 스타일 규칙

Matplotlib 문서의 일관성을 위해 노력하는 것이 유용합니다. 다음은 사용되는 몇 가지 서식 및 스타일 규칙입니다.

섹션 서식

최상위 챕터를 제외한 모든 경우 섹션 제목에 사용 합니다 .Upper lowerPossible hangupsPossible Hangups

섹션 마크업 문자에 대한 Python 문서 및 Sphinx reStructuredText 문서 의 권장 사항을 따르는 것을 목표로 합니다 .

• #오버라인 포함, 부품용. 이것은 의 메인 타이틀용으로 예약되어 index.rst있습니다. 다른 모든 페이지는 "챕터" 이하로 시작해야 합니다.

• *오버라인 포함, 챕터용

• =, 섹션의 경우

• -, 하위 섹션

• ^, 하위 섹션의 경우

• ", 단락의 경우

이는 기존 문서에서 아직 일관되게 적용되지 않을 수 있습니다.

함수 인수

독스트링 내의 함수 인수 및 키워드는 *emphasis*역할을 사용하여 참조해야 합니다. 이렇게 하면 Matplotlib의 문서가 Python의 문서와 일관되게 유지됩니다.

Here is a description of *argument*

다음 을 사용하지 마십시오 .`default role`

Do not describe `argument` like this.  As per the next section,
this syntax will (unsuccessfully) attempt to resolve the argument as a
link to a class or method in the library.

역할 ``literal``:

Do not describe ``argument`` like this.

다른 문서 및 섹션 참조

Sphinx 는 문서 간의 내부 참조 를 허용 합니다.

:doc:문서는 다음 지시문 과 연결될 수 있습니다 .

See the :doc:`/users/installing/index`

See the tutorial :doc:`/tutorials/introductory/quick_start`

See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`

다음과 같이 렌더링됩니다.

설치 참조

튜토리얼 빠른 시작 가이드 보기

예제 단순 플롯 을 참조하십시오.

섹션에 참조 이름을 지정할 수도 있습니다. 예를 들어 설치 링크에서:

.. _clean-install:

How to completely remove Matplotlib
===================================

Occasionally, problems with Matplotlib can be solved with a clean...

표준 참조 구문을 사용하여 참조하십시오.

See :ref:`clean-install`

다음 링크를 제공합니다: Matplotlib를 완전히 제거하는 방법

섹션 레이블 지정 및 참조의 내부 일관성을 최대화하려면 섹션 참조에 하이픈으로 구분된 설명 레이블을 사용하십시오. 콘텐츠는 나중에 재구성될 수 있으므로 필요한 경우가 아니면 user또는 devel 또는 같은 참조에서 최상위 수준 이름을 사용하지 마십시오. 예를 들어 FAQ "백엔드란 무엇입니까?" faq나중에 사용자 가이드의 일부가 될 수 있으므로 레이블은 다음과 같습니다.

.. _what-is-a-backend:

보다 낫다:

.. _faq-backend:

또한 밑줄은 Sphinx 자체에서 널리 사용되므로 하이픈을 사용하여 단어를 구분합니다.

다른 코드 참조

Matplotlib의 다른 메서드, 클래스 또는 모듈에 연결하려면 백틱을 사용할 수 있습니다. 예를 들면 다음과 같습니다.

`matplotlib.collections.LineCollection`

다음과 같은 링크를 생성합니다. matplotlib.collections.LineCollection.

참고: , 등 의 한정자를 사용할 필요가 없도록 sphinx 설정 을 사용 합니다.default_role = 'obj':class::func::meth:

전체 패키지 및 모듈 이름을 표시하고 싶지 않은 경우가 많습니다. 대상이 모호하지 않은 한 간단히 생략할 수 있습니다.

`.LineCollection`

링크는 여전히 작동합니다: LineCollection.

이름이 같은 코드 요소가 여러 개 있는 경우(예: plot()여러 클래스의 메서드) 정의를 확장해야 합니다.

`.pyplot.plot` or `.Axes.plot`

이들은 pyplot.plot또는 로 표시됩니다 Axes.plot. 여전히 마지막 세그먼트만 표시하려면 물결표를 접두사로 추가할 수 있습니다.

`~.pyplot.plot` or `~.Axes.plot`

plot또는 로 렌더링됩니다 plot.

다른 패키지도 intersphinx 를 통해 연결할 수 있습니다 .

`numpy.mean`

이 링크를 반환합니다: numpy.mean. 이것은 Python, Numpy, Scipy 및 Pandas에서 작동합니다(전체 목록은 에 doc/conf.py있음). 외부 연결이 실패하면 다음 명령을 사용하여 참조 가능한 개체의 전체 목록을 확인할 수 있습니다.

python -m sphinx.ext.intersphinx 'https://docs.python.org/3/objects.inv'
python -m sphinx.ext.intersphinx 'https://numpy.org/doc/stable/objects.inv'
python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/scipy/objects.inv'
python -m sphinx.ext.intersphinx 'https://pandas.pydata.org/pandas-docs/stable/objects.inv'

그림 및 파일 포함

image::이미지 파일은 디렉티브 가 있는 페이지에 직접 포함될 수 있습니다 . 예를 들어 tutorials/intermediate/constrainedlayout_guide.py몇 가지 정적 이미지를 표시합니다.

# .. image:: /_static/constrained_layout_1b.png
#    :align: center

파일은 그대로 포함될 수 있습니다. 예를 들어 LICENSE파일은 사용권 계약 에 다음 을 사용하여 포함됩니다.

.. literalinclude:: ../../LICENSE/LICENSE

예제 디렉토리는 sphinx-gallery에 의해 복사 doc/gallery되므로 예제 디렉토리의 플롯은 다음을 사용하여 포함될 수 있습니다.

.. plot:: gallery/lines_bars_and_markers/simple_plot.py

작성된 플롯이 아니라 플롯을 생성하는 Python 스크립트가 참조됩니다. Sphinx-gallery는 문서가 작성될 때 올바른 참조를 제공합니다.

독스트링 쓰기

대부분의 API 문서는 독스트링으로 작성됩니다. 코드 작동 방식을 설명하는 소스 코드의 주석 블록입니다.

메모

문서의 일부는 아직 현재 문서 스타일을 따르지 않습니다. 확실하지 않은 경우 소스 코드에서 볼 수 있는 규칙이 아니라 여기에 제공된 규칙을 따르십시오. 독스트링을 현재 스타일로 업데이트하는 풀 리퀘스트는 매우 환영합니다.

모든 신규 또는 편집된 독스트링은 numpydoc 독스트링 가이드 를 준수해야 합니다 . 위에서 설명한 ReST 구문( ReST 페이지 작성 ) 의 대부분은 링크 및 참조에 사용할 수 있습니다. 이러한 docstring은 결국 doc/api디렉토리를 채우고 라이브러리에 대한 참조 문서를 형성합니다.

독스트링 예시

docstring의 예는 다음과 같습니다.

def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
           label='', **kwargs):
    """
    Plot horizontal lines at each *y* from *xmin* to *xmax*.

    Parameters
    ----------
    y : float or array-like
        y-indexes where to plot the lines.

    xmin, xmax : float or array-like
        Respective beginning and end of each line. If scalars are
        provided, all lines will have the same length.

    colors : list of colors, default: :rc:`lines.color`

    linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional

    label : str, default: ''

    Returns
    -------
    `~matplotlib.collections.LineCollection`

    Other Parameters
    ----------------
    data : indexable object, optional
        DATA_PARAMETER_PLACEHOLDER
    **kwargs :  `~matplotlib.collections.LineCollection` properties.

    See Also
    --------
    vlines : vertical lines
    axhline : horizontal line across the Axes
    """

hlines이것이 렌더링되는 방법에 대한 설명서를 참조하십시오 .

Sphinx 웹사이트 에는 ReST 마크업 및 일반적으로 Sphinx 작업에 관한 많은 문서 가 포함되어 있습니다.

서식 규칙

기본 docstring 규칙은 numpydoc docstring 가이드 및 Sphinx 문서에서 다룹니다. 염두에 두어야 할 몇 가지 Matplotlib 관련 서식 규칙:

견적 위치

한 줄 독스트링에 대한 따옴표는 같은 줄에 있습니다(pydocstyle D200):

def get_linewidth(self):
    """Return the line width in points."""

여러 줄 독스트링에 대한 따옴표는 별도의 줄에 있습니다(pydocstyle D213):

def set_linestyle(self, ls):
"""
Set the linestyle of the line.

[...]
"""

함수 인수

독스트링 내의 함수 인수 및 키워드는 *emphasis*역할을 사용하여 참조해야 합니다. 이렇게 하면 Matplotlib의 문서가 Python의 문서와 일관되게 유지됩니다.

If *linestyles* is *None*, the default is 'solid'.

또는 다음 역할을 사용하지 마십시오 .`default role```literal``

Neither `argument` nor ``argument`` should be used.

문자열에 대한 따옴표

Matplotlib에는 작은따옴표를 사용할지 큰따옴표를 사용할지에 대한 규칙이 없습니다. 현재 코드에는 두 가지가 혼합되어 있습니다.

문자열 값을 제공할 때 간단한 작은따옴표 또는 큰따옴표를 사용하십시오.

If 'tight', try to figure out the tight bbox of the figure.

No ``'extra'`` literal quotes.

텍스트 주위에 여분의 리터럴 따옴표를 사용하는 것은 권장되지 않습니다. 렌더링된 문서를 약간 개선하지만 입력하기 번거롭고 일반 텍스트 문서에서 읽기 어렵습니다.

매개변수 유형 설명

매개변수 유형 설명의 주요 목표는 사람이 읽고 이해할 수 있도록 하는 것입니다. 가능한 유형이 너무 복잡한 경우 유형 설명에 단순화를 사용하고 텍스트에서 유형을 더 정확하게 설명하십시오.

일반적으로 numpydoc docstring 가이드 규칙이 적용됩니다. 다음 규칙은 numpydoc 규칙이 구체적이지 않은 경우 확장됩니다.

float모든 숫자가 될 수 있는 유형에 사용 합니다.

2D 위치를 설명하는 데 사용 합니다. 튜플성을 보다 명확하게 하려면 괄호를 포함해야 합니다.(float, float)

array-like일반적으로 numpy.array일 수 있는 동종 숫자 시퀀스에 사용 합니다. 2D차원은 , 3D, 를 사용하여 지정할 수 있습니다 n-dimensional. 치수의 크기를 나타내는 변수가 필요한 경우 괄호( ) 안에 대문자를 사용 하십시오. 텍스트에서 참조할 때 읽기가 더 쉽고 특별한 서식이 필요하지 않습니다. 반환된 객체가 실제로 numpy 배열인 경우 반환 유형 대신 사용하십시오 .(M, N) array-likearrayarray-like

floatarray-likes에 대한 암시적 기본 dtype입니다. 다른 dtype의 경우 .array-like of int

몇 가지 가능한 용도:

2D array-like
(N,) array-like
(M, N) array-like
(M, N, 3) array-like
array-like of int

숫자가 아닌 동종 시퀀스는 다음과 같이 목록으로 설명됩니다.

list of str
list of `.Artist`

참조 유형

일반적으로 다른 코드 참조 규칙이 적용됩니다. 더 구체적으로:

`~matplotlib.colors.Normalize`매개변수 유형에서 물결표 약어와 함께 전체 참조를 사용하십시오 . 전체 이름은 일반 텍스트 docstring의 독자에게 도움이 되지만 HTML은 링크할 때 전체 이름을 표시할 필요가 없습니다. 따라서 ~-shortening은 더 읽기 쉽게 유지합니다.

`.Normalize`텍스트에 축약된 링크를 사용하십시오 .

norm : `~matplotlib.colors.Normalize`, optional
     A `.Normalize` instance is used to scale luminance data to 0, 1.

기본값

numpydoc 가이드와 달리 매개변수 에 간단한 기본값이 있는 경우 매개변수를 선택사항 으로 표시할 필요가 없습니다.

• 가능할 때 사용 하십시오.{name} : {type}, default: {val}

• 권장되는 방식으로 충분히 설명할 수 없는 경우 텍스트의 기본값을 사용 하고 설명합니다.{name} : {type}, optional

기본값은 인간 독자를 대상으로 하는 시맨틱 정보를 제공해야 합니다. 간단한 경우에는 함수 서명의 값을 다시 나타냅니다. 해당되는 경우 단위를 추가해야 합니다.

Prefer:
    interval : int, default: 1000ms
over:
    interval : int, default: 1000

없음 이 "지정되지 않은 매개변수"에 대한 센티넬 값으로만 ​​사용되는 경우 이를 기본값으로 문서화하지 마십시오 . 컨텍스트에 따라 실제 기본값을 제공하거나 지정하지 않아도 특별한 효과가 없는 경우 매개변수를 선택사항으로 표시하십시오.

Prefer:
    dpi : float, default: :rc:`figure.dpi`
over:
    dpi : float, default: None

Prefer:
    textprops : dict, optional
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.
over:
    textprops : dict, default: None
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.

See also섹션

Sphinx는 섹션의 정의 블록에 있는 코드 요소를 자동으로 연결합니다. 백틱을 사용할 필요가 없습니다.See also

See Also
--------
vlines : vertical lines
axhline : horizontal line across the Axes

래핑 매개변수 목록

긴 매개변수 목록은 \for 연속을 사용하여 래핑해야 하며 들여쓰기 없이 새 줄에서 시작해야 합니다(pydoc이 docstring을 구문 분석하고 줄 연속을 제거하므로 들여쓰기로 인해 줄 안에 공백이 많이 생길 수 있으므로 들여쓰기가 필요하지 않습니다).

def add_axes(self, *args, **kwargs):
    """
    ...

    Parameters
    ----------
    projection : {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
'rectilinear'}, optional
        The projection type of the axes.

    ...
    """

또는 docstring의 전용 섹션에서 유효한 매개변수 값을 설명할 수 있습니다.

rc파라미터

rcParams는 파일 설명 에 대한 링크인 사용자 정의 :rc:역할 :rc:`foo`yields 로 참조할 수 있습니다.rcParams["foo"] = 'default'matplotlibrc

세터와 게터

아티스트 속성은 setter 및 getter 메서드를 사용하여 구현됩니다(Matplotlib가 Python property데코레이터보다 이전이기 때문). 규칙에 따라 이러한 세터와 게터는 이름이 지정 set_PROPERTYNAME되고 get_PROPERTYNAME; 이와 같이 아티스트에 정의된 속성 목록과 그 값은 setp및 getp기능으로 나열할 수 있습니다.

속성 setter 메서드의 매개 변수 블록은 허용된 값을 문서화하기 위해 구문 분석됩니다(예: 다음으로 Line2D.set_linestyle시작 하는 독스트링).

def set_linestyle(self, ls):
    """
    Set the linestyle of the line.

    Parameters
    ----------
    ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
        etc.
    """

plt.setp(line)or 의 출력에서 ​​다음 줄이 생성됩니다 .plt.setp(line, "linestyle")

linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

일부 드문 경우(대부분 단일 튜플과 압축 해제된 튜플을 모두 허용하는 setter)에서 허용된 값을 이러한 방식으로 문서화할 수 없습니다. 이 경우 다음과 같이 블록 으로 문서화할 수 있습니다 ... ACCEPTS:axes.Axes.set_xlim

def set_xlim(self, ...):
    """
    Set the x-axis view limits.

    Parameters
    ----------
    left : float, optional
        The left xlim in data coordinates. Passing *None* leaves the
        limit unchanged.

        The left and right xlims may also be passed as the tuple
        (*left*, *right*) as the first positional argument (or as
        the *left* keyword argument).

        .. ACCEPTS: (bottom: float, top: float)

    right : float, optional
        etc.
    """

선행 ..은 블록을 reST 주석으로 만들어 렌더링된 문서에서 숨깁니다... ACCEPTS:

키워드 인수

메모

이 섹션의 정보는 개발 팀에서 활발히 논의되고 있으므로 필요한 경우에만 docstring 보간을 사용하십시오. 이 보간은 기존 문서의 일부이기 때문에 이 섹션은 지금 그대로 두었습니다.

Matplotlib는 kwargs예를 들어 줄을 만드는 모든 함수( plot, semilogx, 등)에서 많은 pass-through를 사용하기 때문에 새로운 사용자가 어떤 것이 지원 semilogy되는지 알기 어려울 수 있습니다 . kwargsMatplotlib는 docstring 보간 체계를 사용하여 **kwargs. 요구 사항은 다음과 같습니다.

1. 구성의 단일 지점이므로 속성을 변경해도 여러 독스트링 편집이 필요하지 않습니다.

2. 가능한 한 자동화하여 속성이 변경되면 문서가 자동으로 업데이트됩니다.

@_docstring.interpd데코레이터는 이것을 구현합니다 . Line2D통과를 허용하는 모든 함수 kwargs(예: ) 는 다음과 같이 속성 matplotlib.axes.Axes.plot요약을 나열할 수 있습니다 .Line2D

# in axes.py
@_docstring.interpd
def plot(self, *args, **kwargs):
    """
    Some stuff omitted

    Other Parameters
    ----------------
    scalex, scaley : bool, default: True
        These parameters determine if the view limits are adapted to the
        data limits. The values are passed on to `autoscale_view`.

    **kwargs : `.Line2D` properties, optional
        *kwargs* are used to specify properties like a line label (for
        auto legends), linewidth, antialiasing, marker face color.
        Example::

        >>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2)
        >>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2')

        If you specify multiple lines with one plot call, the kwargs apply
        to all those lines. In case the label object is iterable, each
        element is used as labels for each set of data.

        Here is a list of available `.Line2D` properties:

        %(Line2D:kwdoc)s
    """

%(Line2D:kwdoc)구문은 이라는 하위 클래스 를 interpd조회하고 해당 클래스 를 호출 합니다. 하위 클래스를 검사하고 해당 속성을 하위 문자열로 요약하여 docstring에 보간합니다.ArtistLine2Dartist.kwdocartist.kwdoc

__init__하위 클래스와 해당 속성이 해당 지점에서 아직 정의되지 않았기 때문에 이 체계는 아티스트의 를 장식하는 데는 작동 하지 않습니다. 대신 @_docstring.interpd클래스 자체를 장식하는 데 사용할 수 있습니다. 이 시점에서 kwdoc속성을 나열하고 __init__.__doc__.

독스트링 상속

하위 클래스가 메서드를 재정의하지만 의미를 변경하지 않는 경우 자식 클래스의 메서드에 대해 부모 docstring을 재사용할 수 있습니다. 파이썬은 하위 클래스 메서드에 독스트링이 없으면 자동으로 이 작업을 수행합니다.

일반 주석 을 사용하여 부모 docstring을 재사용하려는 의도를 나타냅니다. 그렇게 하면 나중에 실수로 docstring을 만들지 않습니다.# docstring inherited

class A:
    def foo():
        """The parent docstring."""
        pass

class B(A):
    def foo():
        # docstring inherited
        pass

숫자 추가

위와 같이( 그림 및 파일 포함 참조 ) 예제 갤러리 의 그림은 그림을 생성한 Python 스크립트를 가리키는 지시문을 사용하여 참조할 수 있습니다. 예를 들어 docstring은 다음 파일을 참조합니다 ... plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

.. plot:: gallery/text_labels_and_annotations/legend.py
"""

문서의 향후 재구성에서 수정될 수 있는 리디렉션인 에 examples/text_labels_and_annotations/legend.py매핑되었습니다 .gallery/text_labels_and_annotations/legend.py

플롯은 독스트링 안에 직접 배치할 수도 있습니다. 자세한 내용은 matplotlib.sphinxext.plot_directive 에 있습니다. 간단한 예는 다음과 같습니다.

"""
...

Examples
--------

.. plot::
   import matplotlib.image as mpimg
   img = mpimg.imread('_static/stinkbug.png')
   imgplot = plt.imshow(img)
"""

예제 스크립트를 참조하는 것보다 이 스타일의 장점은 코드가 대화형 docstring에도 표시된다는 것입니다.

예제 및 자습서 작성

예제 및 자습서는 각각 및 디렉토리 에 이미지 갤러리를 생성하기 위해 Sphinx Gallery 에서 실행되는 Python 스크립트입니다 . 플롯 생성에서 예제를 제외하려면 파일 이름 어딘가에 "sgskip"을 삽입하십시오./doc/gallery/doc/tutorials

이러한 파일의 형식은 비교적 간단합니다. 올바른 형식의 주석 블록은 ReST 텍스트로 처리되고 코드가 표시되며 그림이 빌드된 페이지에 입력됩니다.

예를 들어 Simple Plot/examples/lines_bars_and_markers/simple_plot.py 예제는 다음과 같이 에서 생성됩니다 .

"""
===========
Simple Plot
===========

Create a simple plot.
"""
import matplotlib.pyplot as plt
import numpy as np

# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)

# Note that using plt.subplots below is equivalent to using
# fig = plt.figure and then ax = fig.add_subplot(111)
fig, ax = plt.subplots()
ax.plot(t, s)

ax.set(xlabel='time (s)', ylabel='voltage (mV)',
       title='About as simple as it gets, folks')
ax.grid()
plt.show()

첫 번째 주석 블록은 ReST 텍스트로 처리됩니다. 다른 주석 블록은 Simple Plot 에서 주석으로 렌더링됩니다 .

자습서는 더 길고 일반적으로 하나 이상의 주석 블록(예: 빠른 시작 가이드 )이 있다는 점을 제외하면 정확히 동일한 메커니즘으로 만들어집니다. 첫 번째 주석 블록은 위의 예와 같을 수 있습니다. ReST 텍스트의 후속 블록은 한 줄의 ###문자로 구분됩니다.

"""
===========
Simple Plot
===========

Create a simple plot.
"""
...
ax.grid()
plt.show()

##########################################################################
# Second plot
# ===========
#
# This is a second plot that is very nice

fig, ax = plt.subplots()
ax.plot(np.sin(range(50)))

이러한 방식으로 텍스트, 코드 및 그림이 "노트북" 스타일로 출력됩니다.

sphinx-gallery에 대한 참조

시연된 Matplotlib 기능은 다음과 같이 하단의 주의 사항에 나열되어야 합니다.

###############################################################################
#
# .. admonition:: References
#
#    The use of the following functions, methods, classes and modules is shown
#    in this example:
#
#    - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
#    - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`

이를 통해 sphinx-gallery는 언급된 기능의 미니 갤러리에 예제에 대한 항목을 배치할 수 있습니다. 여기에 기능이 언급되는지 여부는 미니 갤러리 링크가 해당 기능을 설명하는 데 눈에 띄게 도움이 되는지에 따라 결정되어야 합니다. matplotlib.pyplot.subplots예를 들어 서브플롯을 사용하는 모든 예제가 아니라 서브플롯 배치에 관한 예제에서만 언급 합니다.

pyplotAxes 또는 Figure뿐만 아니라 에도 존재하는 함수 는 예제 코드에서 어느 것이 사용되는지에 관계없이 두 참조를 모두 언급해야 합니다. pyplot 참조는 항상 두 번째로 언급해야 합니다 . 위의 예를 참조하십시오.

갤러리의 예시 순서

자습서 및 예제 섹션의 순서와 각 섹션 내의 예제 순서는 다음 내에서 두 단계 프로세스로 결정됩니다 /doc/sphinxext/gallery_order.py.

• 명시적 순서 : 이 파일에는 섹션 순서에 대한 폴더 목록과 하위 섹션 순서에 대한 예제 목록이 포함되어 있습니다. 문서 페이지에 표시되는 항목의 순서는 해당 항목이 해당 목록에 나타나는 순서입니다.

• 암시적 순서 : 폴더나 예제가 해당 목록에 없으면 명시적으로 순서가 지정된 항목 뒤에 추가되며 이러한 모든 추가 항목은 경로 이름(섹션의 경우) 또는 파일 이름(하위 섹션의 경우)별로 정렬됩니다.

결과적으로 갤러리의 특정 위치에 예시를 표시하려면 해당 목록을 예시로 확장하세요. 명확한 순서를 원하지 않거나 필요하지 않은 경우에도 예제의 이름을 일관되게 지정해야 합니다. 즉, 예제의 주요 기능이나 주제를 파일 이름의 첫 번째 단어로 사용하십시오. 예를 들어 이미지 예제는 이상적으로 와 유사한 이름을 지정해야 합니다 imshow_mynewexample.py.

기타

문서 이동

때로는 문서를 이동하거나 통합하는 것이 바람직합니다. 조치를 취하지 않으면 링크가 작동하지 않거나(404) 이전 버전의 문서를 가리키는 링크가 됩니다. 뷰어를 새 페이지로 즉시 리디렉션하는 html 새로 고침으로 이전 페이지를 교체하는 것이 좋습니다. 예를 /doc/topic/old_info.rst들어 /doc/topic/new_info.rst. 우리는 sphinx에게 여전히 html 새로 고침/리디렉션이 있는 이전 파일을 만들도록 지시하는 지시문을 제거 /doc/topic/old_info.rst하고 /doc/topic/new_info.rst삽입 redirect-from합니다(아마도 눈에 띄게 하기 위해 파일 상단 근처에 있을 것입니다).

.. redirect-from:: /topic/old_info

/build/html/topic/old_info.html빌드된 문서에서 이것은 새로 고침이 있는 html 파일을 생성합니다 new_info.html. 두 파일이 다른 하위 디렉토리에 있는 경우:

.. redirect-from:: /old_topic/old_info2

/build/html/old_topic/old_info2.html에 대한 (상대적) 새로 고침이 있는 html 파일을 생성합니다 ../topic/new_info.html.

의 doc 루트에 상대적인 이 지시문의 전체 경로를 사용하십시오 https://matplotlib.org/stable/. /old_topic/old_info2에서 사용자가 찾을 수 있습니다 http://matplotlib.org/stable/old_topic/old_info2. 명확성을 위해 상대 링크를 사용하지 마십시오.

애니메이션 추가

애니메이션은 Sphinx-gallery에서 자동으로 스크랩됩니다. 이것이 바람직하지 않은 경우 mplgithub github 계정을 설정하는 데 사용되었지만 Google 문서 또는 Youtube 비디오 호스팅과 같은 다른 용도로 사용될 수 있는 사용자 이름이 있는 Matplotlib Google/Gmail 계정도 있습니다. 먼저 를 사용하여 애니메이션을 동영상으로 저장한 다음 Matplotlib의 Youtube 채널matplotlib.animation.Animation.save() 에 업로드하고 youtube에서 다음과 같이 제공하는 포함 문자열을 삽입하여 Matplotlib 애니메이션을 문서에 포함할 수 있습니다.

.. raw:: html

   <iframe width="420" height="315"
     src="https://www.youtube.com/embed/32cjc6V0OZY"
     frameborder="0" allowfullscreen>
   </iframe>

동영상을 생성하는 저장 명령의 예는 다음과 같습니다.

ani = animation.FuncAnimation(fig, animate, np.arange(1, len(y)),
    interval=25, blit=True, init_func=init)

ani.save('double_pendulum.mp4', fps=15)

Google 문서의 YouTube 동영상을 mplgithub 계정에 업로드하기 위한 로그인 비밀번호는 Michael Droettboom에게 문의하세요.

상속 다이어그램 생성

클래스 상속 다이어그램은 Sphinx 상속 다이어그램 지시문을 사용하여 생성할 수 있습니다.

예시:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2

탐색 모음 및 스타일

Matplotlib에는 동일한 탐색 모음과 스타일을 공유하는 몇 가지 하위 프로젝트가 있으므로 이들은 mpl_sphinx_theme 에서 스핑크스 테마로 중앙 집중화됩니다 . 스타일 또는 상단 표시줄에 대한 변경 사항은 모든 하위 프로젝트에 전파되도록 만들어야 합니다.