[Sphinx] 재구성된 텍스트(ReST) 파일에 미디어 삽입

Sphinx(파이썬 정적 사이트 생성기)를 사용하여 문서를 작성하는 경우 ReST(ReStructured Text)라는 일반 마크업 언어를 배워야 합니다. ReST는 매우 고유한 구문을 가지고 있으므로 이 파일에 미디어를 삽입할 수 있는 방법이 얼마나 많은지 궁금하다면 계속 읽으십시오!

따라서 이 자습서를 따르려면 적어도 reST 구문에 대한 기본적인 이해가 있어야 합니다. directive이 무엇인지 아는 것만으로도 시작할 수 있습니다.

이미지 또는 gif와 같은 미디어를 삽입하려면 다음과 같은 지시문을 사용하십시오.
.. image::
.. figure::
.. thumbnail::
● 캡션과 함께 이미지나 GIF를 삽입하려면 figure 지시문을 사용합니다.
● 클릭하면 확대될 수 있는 이미지나 GIF(Lightbox라고도 함)를 삽입하려면 축소판 지시어를 사용합니다. 실제로는 이미지에 대해 항상 이 지시어를 사용하는 것이 좋습니다.
● 이미지 디렉티브를 사용하여 작은 아이콘이나 버튼을 삽입합니다. 이 지시문은 대체 정의에 사용할 수 있기 때문입니다.

썸네일

개인적으로 대부분의 이미지에서 썸네일을 사용해야 합니다. 썸네일은 미디어에 대해 가장 사용자 정의가 가능한 지시어이기 때문입니다. 불행히도 이것은 Sphinx에 내장된 기능이 아니므로 확장 기능으로 제공됩니다. 이 지시문을 사용하려면 먼저 설치한 다음 라이트박스 확장자를 추가하여 conf.py 파일을 구성해야 합니다.

라이트박스 설치

다음 명령을 실행합니다pip install sphinxcontrib-images.

패키지가 성공적으로 설치된 후 conf.py 파일을 열고 다음 확장자를 추가합니다.

 extensions = [
          …
          'sphinxcontrib.images',
          …
          ]

또한 다음 매개 변수를 추가하여 conf.py에서 이미지 동작(예: 너비, 높이, 다운로드 또는 제목)을 추가로 사용자 정의할 수 있습니다.

 images_config = {
    …
 }

예를 들어:

 #lightbox behavior
 images_config = dict(backend='LightBox2',
 default_image_width='100%',
 default_show_title='True',
 default_group='default', )

이제 다음을 사용할 수 있습니다.
.. thumbnail::
ReST 파일의 지시문. 예를 들면 다음과 같습니다.

 .. thumbnail:: path/to/image.png
  :alt: some image
  :align: center
  :title: some image title

여기서 title 속성은 라이트박스가 적용될 때, 즉 이미지를 확대할 때 나타나는 캡션입니다. 제목과 대체 텍스트 모두에 유사한 문구를 사용할 수 있습니다.

Thumbnail 지시문에 사용할 수 있는 다른 속성은 다음과 같습니다.

:download: True 이렇게 하면 원격 이미지를 다운로드할 수 있습니다.

:width: 및 :height: 이들은 매우 자명합니다. 이미지 속성에서 이것을 정의하면 conf.py에서 정의한 기본 백엔드 구성을 재정의합니다.

:group: 이것은 서로 다른 이미지를 함께 그룹화하도록 백엔드에 지시합니다.

수치

이 지시문을 사용하여 클릭하면 이미지를 확대할 수 있지만 확대 효과는 썸네일만큼 부드럽지 않습니다. 이것은 Sphinx에 내장된 기능이므로 먼저 확장 프로그램을 설치할 필요가 없습니다.

Figure 지시문을 사용하는 예:

.. figure:: path/to/image.png
  :width: 200px
  :height: auto
  :alt: some alt text

 _insert image caption here_

위를 보면 .. figure:: 지시문 바로 아래에 여전히 들여쓰기되어 있는 한 그림과 함께 이미지 캡션을 직접 삽입할 수 있습니다(ReST는 들여쓰기에 매우 민감합니다!).

영상

어떤 이유로든 이 두 지시문이 작동하지 않는 경우 최후의 수단이 될 수 있습니다. 그러나 실제로 문서의 다른 페이지에서 동일한 이미지를 재사용해야 하는 경우에 이 기능을 사용할 수 있습니다. 즉, 미리 정의된 키워드를 사용하여 간단히 이미지를 삽입할 수 있습니다.

예를 들어 같은 문장에 인라인 아이콘을 삽입하려고 합니다.

종료 버튼을 클릭 |button-icon| 응용 프로그램을 닫으려면

동일한 파일에서, 바람직하게는 파일 맨 아래에서 다음과 같이 이미지 대체를 정의할 수 있습니다.

.. |button-icon| image:: path/to/image.png
  :width: 30

짜잔! 출력에 인라인 아이콘이 표시됩니다. :)

그게 다야! Sphinx와 함께 일하는 것을 즐기십시오. 챠오카카오.