python kinematics library 인 pykin을 만들면서 문서화를 하기 위해 sphinx 라이브러리를 이용하였습니다.

자주 쓰는 라이브러리가 아니기에 정리하고자 합니다.

이 블로그를 참고하여 작성하였고, 예시를 같이 보여주면서 진행하겠습니다.

Sphinx는 문서 작성을 위한 라이브러리로 소스코드로부터 문서(html , Latex, Markdown)를 정적으로 생성하는 도구입니다.

Sphinx 사용 방법

• Sphinx 설치

  로컬 환경에서 설치해도 되지만 필자는 anaconda를 이용하여 설치하였습니다.

  # Anconda 사용
  $ conda install Sphinx
    
  # Anconda 미사용
  $ pip3 install Sphinx
  

• Sphinx 세팅

  프로젝트 최상위 디렉터리에서 docs 디렉토리를 만든 후 진행합니다.

  $ cd ~/pykin
  $ mkdir docs
  $ cd docs
  $ sphinx-quickstart
  

  

• Sphinx 빌드

  생성된 Makefile을 이용해 빌드합니다.

  $ make html
  

  

• conf.py 수정

  • 수정 사항
    1. 최상단의 os.path 수정
    2. extensions 추가
    3. sphinx_rtd_theme 테마 적용

  $ cd source
  $ vi conf.py
  

  ############# 수정 1 #############
  import os
  import sys
  sys.path.insert(0, os.path.abspath('../..'))
  #################################
    
  project = 'pykin'
  copyright = '2021, daejong jin'
  author = 'daejong jin'
    
  # The full version, including alpha/beta/rc tags
  release = '1.0'
    
  ############# 수정 2 #############
  extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.doctest',
      'sphinx.ext.intersphinx',
      'sphinx.ext.todo',
      'sphinx.ext.coverage',
      'sphinx.ext.mathjax',
      'sphinx.ext.viewcode',
      'sphinx.ext.napoleon'
  ]
  #################################
  templates_path = ['_templates']
  exclude_patterns = []
    
  ############# 수정 3 #############
  html_theme = 'sphinx_rtd_theme'
  #################################
  html_static_path = ['_static']
  

  위의 예시와 같이 수정된 부분을 참고하여 따라 작성합니다.

• rst 파일 생성

  최상단 디렉토리로 이동하여 다음의 명령어를 실행합니다.

  $ cd ~/pykin
  $ sphinx-apidoc -f -o docs/source pykin
    
  

  

• 빌드

  rst 파일이 생성되었음을 확인하였으면 이전과 같이 Makefile을 이용해 빌드 합니다.

  $ cd docs
  $ make html
  

• html 파일 확인

  build 디렉토리 안 html 파일을 열어 확인하면 됩니다.

  

• 빌드 된 html 디렉토리 최상위 디렉토리 경로 안으로 복사

  기존 docs 디렉토리는 docs_backup이라 변경하고

  build 디렉토리 안에 있는 html 디렉토리를 최상단 디렉토리에 복사 후 이름을 변경합니다.

  $ cd ~/pykin
  $ mv docs docs_backup
  $ cp -r docs_backup/build/html docs
  

• Git push

  최종적으로 Github에 push 합니다.

Github page 설정

• Github page에 들어가서 아래의 빨간 상자모양 Setting을 클릭합니다

  

• Github Pages에 Check it out here 버튼을 클릭합니다.

  

• Source 란에서 branch /docs 폴더를 선택합니다.

  

• 아래의 주소를 입력하면 원하던 페이지가 나오게 됩니다.

  

  

Docstring 작성법

"""
====================================
 :mod:`a` pykin
====================================

설명
=====
이 모듈은 문서화 테스트를 위한 모듈입니다.

"""
class ContactData:
    """
    Data structure for holding information about a collision contact.

    Args:
        names (str): The names of the two objects in order.
        contact (fcl.Contact): The contact in question.
    """

    def __init__(self, names, contact):
        self.names = set(names)
        self._inds = {
            names[0]: contact.b1,
            names[1]: contact.b2
        }
        self._point = contact.pos
        self._depth = contact.penetration_depth

    def index(self, name):
        """
        Returns the index of the face in contact for the mesh with
        the given name.

        Args:
            name (str): The name of the target object.

        Returns:
            int: The index of the face in collision
        """
        return self._inds[name]