Sphinx 사용법

참고

https://www.sphinx-doc.org/en/master/tutorial/first-steps.html

명령들

sphinx(스핑크스) 설치 : pip install sphinx
sphinx 버전 확인 : sphinx-build –version
documentation layout 생성 : sphinx-quickstart docs
sphinx-build : sphinx-build -M html docs/source docs/build
문서 수정 후 make html 명령 실행
html말고 epub (make epub), PDF 등으로 출력 가능
EPUB-compatible e-book viwer, Calibre

rst 문법 일반

#Section Header
=============
-------------
`````````````
''''''''''''''

-
    -
        -

1.
2.
    1.
        -
#.

표

Grid table이랑 Simple table있음.

Simple table

=========  =============
Bit      Description
=========  =============
#15~1      reserved
#0 Byte
         - 1 : 기본 주파수 50Hz
         - 0 : 기본 주파수 60Hz
=========  =============


=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
      Second line of paragraph.
3      - Second column of row 3.
      - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

Bit	Description
#15~1	reserved
#0 Byte	1 : 기본 주파수 50Hz 0 : 기본 주파수 60Hz

col 1	col 2
1	Second column of row 1.
2	Second column of row 2. Second line of paragraph.
3	Second column of row 3. Second item in bullet list (row 3, column 2).
	Row 4; column 1 will be empty.

code 넣기

.. code-block:: console

   pip install furo

<결과>

pip install furo

cross-reference 넣기

doc:

프로젝트의 특정 문서를 자동으로 참조함
:ref프로젝트의 임의 부분에 cross-reference를 추가할 수도 있음
- 대상에 레이블 추가해야 함

# 레이블 추가

.. _command_list:

명령들
---------------

#cross-reference 추가

:doc:`video` section으로 이동할 수 있으며
여기 문서의 :ref:`명령들 <command_list>` 로 이동할 수 있음.

Video/video section으로 이동할 수 있으며 여기 문서의 명령들 로 이동할 수 있음.

note 넣기

.. note::

   This project is under active development.

<결과>

참고

This project is under active development.

이미지 넣기

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

youtube 영상 넣기

설치 : pip install sphinxcontrib-youtube
conf.py 에 추가

extensions = [
   ...
   'sphinxcontrib.youtube',
   ...
]

.. youtube:: VIDEO_ID
   :width: 560
   :height: 315

VIDEO_ID는 url 끝에 붙은 id –> FRSb44jqovM 이렇게 생김.

수평선 넣기

ABC

-----------

DEF

<결과> ABC

DEF

윗첨자 넣기

:math:`10^{-5}`

<결과> \(10^{-5}\)

pdf 문서 넣기

설치 방법 : sphinxcontrib-pdfembed
- sphinxcontrib-pdfembed는 pip을 통해 설치할 수 있는 Sphinx 플러그인이 아닙니다. 따라서 pip install sphinxcontrib-pdfembed 명령을 사용하여 직접 설치할 수는 없습니다.
- 대신, sphinxcontrib-pdfembed 플러그인을 설치하려면 해당 프로젝트의 소스 코드를 다운로드하고 수동으로 설치해야 합니다. 일반적으로 GitHub에서 플러그인의 소스 코드를 다운로드한 후, 설치 지침을 따라 수동으로 설치합니다.
- 따라서 sphinxcontrib-pdfembed를 설치하려면 다음과 같은 단계를 따라야 합니다:
- sphinxcontrib-pdfembed 플러그인의 GitHub 저장소에서 소스 코드를 다운로드하십시오.
- 압축을 해제하고, 명령 프롬프트나 터미널에서 해당 디렉터리로 이동합니다.
- setup.py 파일이 있는 디렉터리에서 다음 명령을 실행하여 플러그인을 설치합니다.
- python setup.py install
conf.py 에 추가

extensions = [
   ...
   'sphinxcontrib.pdfembed',
   ...
]

:pdfembed:`src:_static/XR조사_세미나(한유림).pdf, height:1600, width:1300, align:middle`

Documenting Python objects

Documenting Python Object 예제
--------------------------------

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]

<결과>

Documenting Python Object 예제

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

lumache.get_random_ingredients(kind=None)

Return a list of random ingredients as strings.

매개변수:: kind (list[str] or None) – Optional “kind” of ingredients.
반환:: The ingredients list.
반환 형식:: list[str]