8/01/2021

Sphinx 기반의 문서정리-1

1. Sphinx 설치 

  • Python venv기반으로 구성 
호환성문제로 virtualenv를 사용하기로 결정했으며, 상위참조하여 생성 
$ 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 기본사용법



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 찾고 설치진행 후 상위와 동일하게 설정 



1.3. Sphinx extension 설정 (conf.py)

  • sphinx에서 필요한 기능을 확장하여 설정
  1. extension 기능을 사용하기 위해서 아래와 같이 python 소스의 주석을 제거한 후 진행 
  2. 원하는 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로 생성된 파일확인 






상위 sphinx quickstart 기본설명
  https://www.sphinx-doc.org/en/master/usage/quickstart.html

댓글 없음 :