sphinx-js 로 javascript 코드 문서화하기

블로그 글 상단/하단에 간헐적으로 뜨는 광고는 블로그 개인 수익과 관련 없는 티스토리 측 광고입니다

 

 

소개

 

안녕하세요. 오늘은 javascript로 코딩된 프로젝트의 문서화를 위한 sphinx-js를 설명해드리려고 합니다.

sphinx는 python 프로젝트의 문서 자동화를 위한 툴입니다. python 프로젝트의 함수, 모듈들에 특정 문법을 따라 주석을 작성해 두면 자동으로 latex 문서, html로 빌드해 주는 툴이에요. 오픈 소스 프로젝트의 문서화 등에 많이 사용합니다.

javascript용으로 유사한 툴 jsdoc 이 있지만, read-the-docs 와 연동해서 빌드하고 싶어서 찾게 된 게  바로 sphinx-js예요.

 

 

GitHub - mozilla/sphinx-js: Autodoc-style extraction into Sphinx for your JS project

 

sphinx-js를 사용하면 기존의 python sphinx 프로젝트들 처럼 docs html을 빌드할 수 있고, 더불어 latex 문서로도 빌드가 가능합니다. docs 폴더를 페이지 내에 넣어놓으면 github에서 바로 페이지로 redirection 시킬 수 있다는 장점이 있습니다. sphinx와 함께 많이 쓰이는 Read-the-Docs (RTD)는 sphinx로 만들어진 html 문서를 호스팅 할 수 있는 곳입니다. 최근 python 기반의 많은 open source 프로젝트들이 활용하고 있는 웹 호스팅 사이트예요.

 

정리하자면,

• sphinx는 python으로 작성된 프로젝트의 주석을 읽어 들여 html, latex 등의 포맷으로 문서화해 준다.
• RTD는 sphinx를 통해 생성된 html의 웹 호스팅을 깔끔하게 해주는 툴로, 다양한 테마들을 지원하고 있다.
• javascript 기반 프로젝트의 RTD 웹 호스팅을 위해 sphinx-js를 사용하는 방법을 소개해드리겠습니다.

 

Read-The-Docs를 사용해서 deploy한 javascript 프로젝트 문서화 페이지 예시.

 

 

 

 

설치

 

sphinx-js는 jsdoc과 sphinx-js를 모두 설치해야 합니다. 참고로 jsdoc은 javascript 모듈이고 sphinx-js는 python 모듈이에요. 그러니 각각 아래 명령어를 사용해서 설치해 줍니다.

 

npm install -g jsdoc

 

pip install sphinx-js

 

(+) 추가로 sphinx를 잘 활용하기 위한 패키지들을 설치해 주겠습니다. (sphinx-js를 위해서 필수는 아니지만, RTD와의 연동 및 MD 파일의 문서화를 위해서 필요한 패키지입니다.)

 

• sphinx에서 마크다운을 활용하기 위한 패키지, myst_parser
• RTD 테마 적용하기 위한 패키지, sphinx_rtd_theme

pip install sphinx_rtd_theme
pip install myst_parser

 

(+) 에러핸들링

ImportError: cannot import name 'soft_unicode' from 'markupsafe' (~/opt/anaconda3/envs/sphinx/lib/python3.8/site-packages/markupsafe/init.py)

pip install markupsafe==2.0.1

 

설정

 

sphinx-js는 sphinx에서 javascript를 지원할 수 있도록 하는 모듈이라고 볼 수 있습니다. 그래서 sphinx의 기본적인 설정을 따라가되 sphinx-js 모듈을 추가로 설정해 주고 javascript 코드 내의 주석 문법은 sphinx-js에서 사용하는 jsdoc 명령어를, docs 문서의 문법은 sphinx의 RTD 포맷을 따르면 됩니다.

 

|       1.  sphinx 세팅하기 (sphinx-quickstart) 

 

이제 프로젝트 파일 경로로 이동 후 sphinx-quickstart 명령어를 진행합니다. 명령어 진행 시 실제 documentation 관련 파일들을 저장할 경로를 지정할 수 있으며, 일반적으로 docs라는 폴더 내에 관리하는 경우가 많으므로 저는 sphinx-quickstart docs라는 명령어를 전달해 줄게요.

cd my-project
sphinx-quickstart docs

 

 

그러면 기본적으로 sphinx에 필요한 폴더 및 파일들이 docs/ 폴더 밑에 생성됩니다.

 

/my_project
|_/yourcodes
|_/docs
|    |_Makefile
|    |_Requirement.txt
|    |_ build/
|    |_ source/
|    |    |_ _static
|    |    |_ _templates
|    |    |_ conf.py
|    |    |_ index.rst
|    |_ make.bat
|_jsdoc.json

 

 

|      2. sphinx_js를 Requirement.txt에 추가하기

 

sphinx를 사용해서 빌드할 때 sphinx_js를 쓰도록 설정해주어야 합니다. 이때, sphinx에서 필요한 모듈 (dependency)를 확인하는 파일이 Requirement.txt입니다.  저 같은 경우에는 sphinx-js 외에도 rtd 테마, 그리고 mark down 자동 파싱을 위한 parser를 추가해 주었습니다.

 

myst-parser==0.18.0
sphinx_rtd_theme==1.1.1
sphinx-js==3.1.2

 

|      3. sphinx_js로 설정해 주기

 

이제 sphinx_js extension을 설정해 줍니다. docs/source/ 폴더 내에 생성된 conf.py 파일에서 extensions에 "sphinx_js"를 추가해 주면 됩니다. 추가로 primary_domain 이랑 js_source_path 그리고 jsdoc_config_path를 설정해주어야 합니다.

이때 경로는 conf.py가 있는 source 경로를 기준으로 설정해주어야 해서 아래와 같이 설정해 주었습니다.

 

 

참고로, sphinx_js extension 외에 다른 옵션들 (sphinx_rtd_theme, sphinx.ext.autodoc, myst_parser)은 sphinx 사용에서 필요에 따라 설정해 준 extension들이에요. sphinx 문서화에서 필요한 rtd_theme이나 mark down import용 extension들은 sphinx 문서들을 참고하시면 됩니다.

 

참고, sphinx 설정 가이드 (python용)

 

|      4.  jsdoc.json 편집하기

 

3번 단계까지 수행한 docs/source/ 폴더 아래에서 conf.py 파일 설정들은 sphinx에 대한 설정입니다. sphinx 설정에  "java script를 쓸 거야"라고 extension을 지정해 주고 이때 읽어올 jsdoc_conf_path를 설정해주면 sphinx가 문서화를 수행할 때 지정된 jsdoc.json 파일 경로를 참고해서 javascript 파일들의 주석을 분석해서 문서화해줍니다. 이 때 javascript의 문서화를 수행하기 위한 툴로 jsdoc이 사용됩니다. 

 

제 코드 같은 경우에는 하나의 main 파일에서 모든 패키지를 import 하는 형태여서 아래처럼 주요 main 파일만 include로 넣어주었습니다 (아니면 재귀적으로 모든 파일들이 parsing 돼서 에러가 뜨더라고요)

 

여기서도 주의할 점은 sphinx 가 source 폴더를 기준으로 parsing 하기 때문에 상대 경로를 작성해 줄 때 유의해야 한다는 점입니다. 예를 들어 include의 경우에도 "../../yourcodes/main.js"로 설정해 주었고 destination도 "../../docs"로 설정해 주었어요.

 

{
  "source": {
    "include": ["../../yourcodes/main.js"],
    "includePattern": ".js$",
    "excludePattern": "(node_modules/|docs)"
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  },
  "opts": {
    "recurse": true,
    "destination": "../../docs/"
  }
}

 

 

문서화

 

두서없이 설명했지만, 정리하자면 sphinx-js를 사용한 코드 문서화는 두 개의 모듈을 사용합니다. 1. sphinx 2. jsdoc.  이 둘을 연결시켜 주는 모듈이 sphinx-js인 셈입니다. 이제 각각의 포맷에 맞춰서 문서화를 위한 추가 파일들을 작성해 줄 겁니다.

 

sphinx의 메인 문서들은 기본적으로 rst 포맷을 따릅니다. make html 명령어를 내렸을 때 설정한 docs/ 폴더 내에 있는 rst 파일들을 읽어 들여 문서화를 해줍니다. 

 

예를 들어, 문서의 구조가 다음과 같다고 가정해 보겠습니다.

index
|_ Introduction
|	|_ intro
|_ Modules
	|_ module1
	|_ module2

 

그렇다면 index.rst는 다음과 같이 작성할 수 있으며 이때 source 폴더 내에는 각각 대응되는 rst 파일을 작성해주어야 합니다. 

.. documentation master file, created by
   sphinx-quickstart on Tue Nov 29 21:07:28 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

타이틀
======================================
문서 설명

.. image:: _static/image.png
    :alt: image example
    :align: center

**Figure**. static image example

====================================================================================

.. toctree::
    :maxdepth: 3
    :caption: Introduction

    intro


.. toctree::
   :maxdepth: 3
   :caption: Modules:

   module1
   module2
   module3


.. Indices and tables
   * :ref:`genindex`
   * :ref:`modindex`
   * :ref:`search`

 

이때, 각각에 대응되는 rst파일은 source 폴더 내에 같은 레벨에서 작성되면 됩니다.

/my_project
|_/yourcodes
|_/docs
|    |_Makefile
|    |_Requirement.txt
|    |_ build/
|    |_ source/
|    |    |_ _static
|    |    |_ _templates
|    |    |_ conf.py
|    |    |_ index.rst
|    |    |_ intro.rst
|    |    |_ module1.rst
|    |    |_ module2.rst
|    |_ make.bat
|_jsdoc.json

 

rst 파일 내에서 javascript 코드의 주석 정보를 불러오려면.. js:autofunction:: someFunction과 같은 문법을 따라 불러오면 됩니다. 각 타입 별 설정은 https://github.com/mozilla/sphinx-js을 참고해 주세요.

..js:autofunction::FunctionName

..js.autoclass:ClassName
  :members:
  :private-members:

 

 

rst 파일에서 위의 jsDoc문법을 통해 자동으로 문서화하기 위해서는 javascript 코드 내에 주석 설명이 추가되어야 합니다. 주석작성을 위한 문법은 jsdoc 문법을 따릅니다.  JSDoc syntax를 참고하시면 됩니다.

 

예)

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

 

 

빌드

 

docs 폴더 내에서 make 명령어를 통해 빌드해 주면 됩니다. 

 

make html

 

 

참고

- https://github.com/mozilla/sphinx-js

GitHub - mozilla/sphinx-js: Autodoc-style extraction into Sphinx for your JS project

- https://jsdoc.app/tags-param.html#parameters-with-properties

Use JSDoc: @param

- https://www.sphinx-doc.org/en/master/usage/quickstart.html#defining-document-structure

Getting Started — Sphinx documentation

 

 

끝 ◼︎