1. Sphinx 설치
- Python venv기반으로 구성
$ python -V //python이 없다면 /us/bin 에서 확인 후 설치 Python 3.8.5 # sudo ln -s /usr/bin/python3 /usr/bin/python //나의 경우 이전에 python2를 python 심볼링크 사용 (옵션) # sudo apt-get install python3-venv //venv 설치 (옵션) $ mkdir works $ cd works $ python -m venv py38-sphinx //py38-sphinx venv 생성 $ ls py38-sphinx $ ls py38-sphinx/bin/ //python 과 python3 는 symbollink 확인 Activate.ps1 activate activate.csh activate.fish easy_install easy_install-3.8 pip pip3 pip3.8 python python3 $ source py38-sphinx/bin/activate //virtual env의 python 사용
매번 py38-sphinx 내부의 virtualenv를 사용하기위해서는 source를 진행하거나, .bashrc 등 기타 로그인때 자동으로 설정해도 된다.
- venv 안에 Python package 설치
sphinx package 설치 및 확인
(py38-sphinx) $ pip list Package Version ------------- ------- pip 20.0.2 pkg-resources 0.0.0 setuptools 44.0.0 (py38-sphinx) $ pip install sphinx //venv에 sphinx 설치 (py38-sphinx) $ pip list Package Version ----------------------------- --------- alabaster 0.7.12 Babel 2.9.1 certifi 2021.10.8 charset-normalizer 2.0.7 docutils 0.17.1 idna 3.3 imagesize 1.2.0 Jinja2 3.0.2 MarkupSafe 2.0.1 packaging 21.0 pip 20.0.2 pkg-resources 0.0.0 Pygments 2.10.0 pyparsing 2.4.7 pytz 2021.3 requests 2.26.0 setuptools 44.0.0 snowballstemmer 2.1.0 Sphinx 4.2.0 sphinxcontrib-applehelp 1.0.2 sphinxcontrib-devhelp 1.0.2 sphinxcontrib-htmlhelp 2.0.0 sphinxcontrib-jsmath 1.0.1 sphinxcontrib-qthelp 1.0.3 sphinxcontrib-serializinghtml 1.1.5 urllib3 1.26.7 (py38-sphinx) $ pip list | wc -l //전부 28 line 이며 -2개를 하면 26 package 가지고 있음(계산하기 귀찮음) 28 (py38-sphinx) $ pip list | wc //newline:28 word:56 byte counts:1120 28 56 1120
Python venv 기본사용법
sphinx 설치 및 기본사용법 (비슷비슷하다)
1.1. sphinx 기본 테스트
- Sphinx 기본사용 및 확인
(py38-sphinx) $ mkdir docs (py38-sphinx) $ cd docs (py38-sphinx) $ sphinx-quickstart // 실행하면, 현재 directory기준 Sphinx 4.0.2 빠른 시작 유틸리티에 오신 것을 환영합니다. 다음 설정에 대한 값을 입력하십시오 (대괄호로 묶여 있는 기본값이 존재하고 이 값을 사용하려면 바로 Enter를 누릅니다). 선택한 루트 경로: . Sphinx 출력을 위한 빌드 디렉토리를 배치하는 두 가지 옵션이 있습니다. 루트 경로 내에서 "_build" 디렉토리를 사용하거나, 루트 경로 내에서 "source"와 "build" 디렉토리로 분리합니다. > 원본과 빌드 디렉토리 분리 (y/n) [n]: > 프로젝트 이름: testSphinx > 작성자 이름: Jeonghun Lee > 프로젝트 릴리스 []: 1.0 문서를 영어 이외의 언어로 작성하려는 경우, 여기에서 해당 언어 코드로 언어를 선택할 수 있습니다. 그러면 Sphinx가 생성한 텍스트를 해당 언어로 번역합니다. 지원되는 코드 목록은 https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language 를 참조하십시오. > 프로젝트 언어 [en]: /home/jhlee/works/docs/conf.py 파일을 만드는 중입니다. /home/jhlee/works/docs/index.rst 파일을 만드는 중입니다. /home/jhlee/works/docs/Makefile 파일을 만드는 중입니다. /home/jhlee/works/docs/make.bat 파일을 만드는 중입니다. 완료됨: 초기 디렉토리 구조가 생성되었습니다. 이제 마스터 파일 /home/jhlee/works/docs/index.rst을(를) 채우고 다른 원본 문서 파일을 만들어야 합니다. Makefile을 사용하여 다음과 같이 문서를 빌드하십시오: make builder 여기서 "builder"는 지원되는 빌더 중 하나(예: html, latex, linkcheck)입니다.
(py3-sphinx) $ ls // 원본과 빌드 디렉토리 분리 [n] 일경우 구성 Makefile _build _static _templates conf.py index.rst make.bat (py38-sphinx) $ ls // 원본과 빌드 디렉토리 분리 [y] 일경우 구성 Makefile build make.bat source (py3-sphinx) $ ls source _static _templates conf.py index.rst (py3-sphinx) $ make html //_build 안에 html 안에 html구성 index.html 확인
- _build/html/index.html
상위내용 및 venv 기반의 sphinx 설정
https://www.docslikecode.com/learn/01-sphinx-python-rtd/1.2. Sphinx의 theme 변경
Sphinx에서 제공하는 Theme들을 찾아 설치 후 이를 설정하고 이 기반으로 변경해보자.
아래는 ReadTheDoc의 theme이며, 이외에도 많으므로 각 설정해보면서 바꾸어 보자.
(py38-sphinx) $ pip install sphinx_rtd_theme //sphinx theme 설치 esp32는 별도로 변경해서 사용함 (py38-sphinx) $ pip list | wc //sphinx_rtd_theme 만 설치됨 29 58 1160 (py38-sphinx) $ vi conf.py //sphinx_rtd_theme 만 변경 #html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' (py3-sphinx) $ make html //_build 안에 html 안에 html구성 index.html 확인
- _build/html/index.html
Sphinx는 이외에도 다양한 Theme을 제공
아래사이트에서 본인이 원하는 Theme 찾고 설치진행 후 상위와 동일하게 설정
Sphinx Theme
1.3. Sphinx extension 설정 (conf.py)
- sphinx에서 필요한 기능을 확장하여 설정
- extension 기능을 사용하기 위해서 아래와 같이 python 소스의 주석을 제거한 후 진행
- 원하는 extension 기능을 아래와 같이 추가
(py38-sphinx) $ vi conf.py //각 관련부분 수정 ## 아래부분은 기본으로 주석으로 되어짐 import os import sys sys.path.insert(0, os.path.abspath('.')) ## 확장기능으로 아래 링크참조 extensions = [ 'sphinx.ext.autodoc', # autodoc 안에 automodule 도 포함 'sphinx.ext.autosummary', # 현재미사용 ] ## 이전설정으로 다른 Theme으로 변경가능 html_theme = 'sphinx_rtd_theme'
extension을 이용하여 다양하게 확장가능
상위에 각각의 링크확인가능
1.4. Sphinx 의 index.rst 설정
- index.rst 파일설정
index.rst 기본값 확인 후 toctree 설정진행
(py38-sphinx) $ cat index.rst //기본설정확인
Welcome to testSphinx's documentation!
======================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
각 구성할 *.rst 파일과 함께 최종 index.rst 에 연결진행
- about.rst 구성
(py38-sphinx) $ vi about.rst //상위에서 source 와 build를 분리하지않음 (분리하면 source 안에)
about
=====
about 에대한 파일이며 이것은 오직 테스트용으로 사용함
.. math::
(a + b)^2 = a^2 + 2ab + b^2
(a - b)^2 = a^2 - 2ab + b^2
- intro.rst 구성
(py38-sphinx) $ vi intro.rst //아래내용들은 toctree 예제참조
intro^^
=========
정말 이게 인트로인지 테스트 해보자
.. note::
This function is not suitable for sending spam e-mails.
.. versionadded:: 2.5
The *spam* parameter.
.. deprecated:: 3.1
Use :func:`spam` instead.
.. seealso::
Module :py:mod:`zipfile`
Documentation of the :py:mod:`zipfile` standard module.
`GNU tar manual, Basic Tar Format ???
Documentation for tar archive files, including GNU tar extensions.
- source.rst
(py38-sphinx) $ vi source.rst
Python source
==============
.. automodule:: pysrc.testclass
:members:
(py38-sphinx) $ mkdir pysrc
(py38-sphinx) $ vi pysrc/testclass.py //아래사이트에서 얻은예제 추가 (상위 conf.py 확장)
"""
My Module
~~~~~~~~~
"""
class Test(object):
"""두 개의 int 값을 입력받아 다양한 연산을 할 수 있도록 하는 클래스.
:param int a: a 값
:param int b: b 값
"""
def __init__(self, a, b):
self._a = a
self._b = b
def is_same(self):
"""미리 입력받은 a와 b값이 같은지 확인하여 결과를 반환합니다.
:return: boolean True or False에 대한 결과, a와 b가 값으면 True, 다르면 False
예제:
다음과 같이 사용하세요:
>>> Test(1, 2).is_same()
False
"""
return self._a == self._b
def plus(self):
"""미리 입력받은 a와 b값을 더한 결과를 반환합니다.
:returns: int a + b에 대한 결과
예제:
다음과 같이 사용하세요:
>>> Test(2, 1).plus()
3
"""
return self._a + self._b
- index.rst 변경
(py38-sphinx) $ vi index.rst //상위에서 추가한 *rst 파일들 추가 혹은 directory 추가
Welcome to my Sphinx TEST !!!!!!!!!!!!
======================================
This is the documentation for TEST
is it ok???
한글도 되는 지 테스트를 해보도록하자 ㅋㅋㅋㅋㅋ
MarkDown 과 유사하지만 "toctree" 별도로 제어로사용??
.. toctree::
:maxdepth: 2
:caption: Table of Contents
:numbered:
about
intro
source
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
(py3-sphinx) $ make html //_build 안에 html 안에 html구성 index.html 확인
- 결과확인
상위설정 후 make html로 생성된 파일확인
rst 관련 파일
toctree 관련예제
python class 경우 doxygen 필요없이 extension의 autodoc 연결
ESP-IDF의 Sphinx 구조파악
상위 sphinx quickstart 기본설명
https://www.sphinx-doc.org/en/master/usage/quickstart.html