누군가 모듈을 만들고 나면, 그에대한 설명을 할필요가 느껴진다. 그런데, 이런 문서화를 하는 방법은, 기본적으로 알아서 글로 만들어서 배포하는 것이 가능한 방법도 있지만, 함수단위로 써진 것을 자동으로 만드는 방법을 누군가 프로그램으로 만든 것이 있는데 이 프로그램이 스핑크스인것이다
이제, 이것을 사용하는 방법을 보여 드립니다



먼저 다음의 조건으로 된 자료를 문서화 하는 것입니다
내가 원하는 부분은 sp_doc안의 xython안의 파이썬화일들을 문서화해서 github에 올리는 것이다

제이먼저 해야 할 것은 바로 필요한 프로그램을 설치하는 것입니다
1 PIP INSTALL SPHINX
PIP INSTALL MYST_PARSER 파이썬용 프로그램을 설치하는것. md파일화 사용하지 않으신다면, myst_parser는 설치하지 않아도 됩니다

2 xython폴더안에 자료를 복사한다

3 cd d:\sp_doc 내가 원하는 위치로 이동



4 PS D:\sp_doc> sphinx-quickstart docs 기본적인 docs폴더에 자료를 만든다

위의것을 사용하지 않고, 전체를 모두 다 내가 작성을 할수도 있지만, 쉽게 사용하라고 만든 기능이다.
그래서 처음에는 이런저런 설정을 하지만, 두번째부터는 어딘가 저장을 해놓고, 이것을 실행한다음에 그냥 복사해서 사용하고 있다

아래와 같은 형태로 선택해서 실행을 하면




위와같이 폴더들과 파일들이 만들어 진다. 이것은 우리가 직접 만들어야하는 파일들을 좀더 쉽게 만들어주는 것이며, 그래서 일반적인 내용이 들어가는 것이라, 그것을 좀 변경 합니다

5 Conf.py파일의 내용을 변경한다



import os
import sys
sys.path.insert(0, os.path.abspath('D:\\sp_doc'))

extensions = [ 'sphinx.ext.autodoc' ,'myst_parser']

html_theme = 'sphinx_rtd_theme'

source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}

화일들 찾아갈 위치는 다른 사이트들에서는 여러 형태를 사용하는데, 그냥 절대경로는 적어주는 것이 가장 이해하기가 쉽워서, 상대경로는 사용하지 않았다

6 Index.html을 변경한다


7 내가원하는 readme.md파일을 source폴더밑에 복사한다



8 파일을 이제 rst형식으로 바꾼다
sphinx-apidoc -F -o docs/source xython Xython은 내가 문서화를 하기위해서 파이썬화일을 넣은 폴더이다
그리고 이안의 모든 파일을 만든 것이 아니고, 전체적으로 html파일을 만들 준비가 다 된것이다





9 docs\make html html파일을 만드는것
아래의 빨간색은 대부분, docstring부분에서 문서화를 하는데, 오류등이 있는 부분이지만, 큰 지장없이 실행이 됩니다

원래는 빨간색으로 나오는 부분이 더 많았는데, 각 파일들에 들어가서 바꿀수있는 부분들은 바꿔서 많이 줄어든 것이다



 

10 다시 html을 만들고 싶을때는, build부분 삭제하시고 다시 실행 하시면 됩니다



 



만약 readme.md파일이 먼저 잇으니, 그 내용이 먼저 나타난다, 즉, 대분류의 개념은 왼쪽과 오른쪽 모두 나타나는 것을 알수가있다
그러니, 필요하면 이 내용들을 잘 변경하면 된다
즉, xython으로 된 부분은 python파일들이 자동으로 문서화가 되는 부분을 위해서 만든 것이며, readme.md는 내가 임으로 만드는 문서를 markdown의 형식으로 만들면, 위와같이 나오는 것을 보이는 목적이다



11 Github에 자료 올리기
먼저, 사이트를 만들어야 겠지요
여기서 만든 파일을 github에 올리는 여러방법이 있는데, 그냥 전문가가 아니면, 편하게 드레그를 해서 올리시기를 권합니다


그리고, 맨 마지막에는 commit changes를 눌러줘야 완료가 된다