드디어 찾았다. 리눅스에서 여러 서비스를 돌리면서, 새로운 프레임워크를 배우면서 많이 참고했던 Document 페이지가 구조가 비슷해보였는데 역시나 제작 툴이 있었다.
내가 찾던 툴은 Sphinx였고 가장 좋아보였던 테마는 Read the Docs였다.
스핑크스를 간단히 소개하자면 파이썬 기반으로 제작된 문서화 도구이다. rst파일이나 마크다운 파일을 HTML과 같은 문서로 변환해주는 도구이다. 맨 위의 스크린샷이 제작 후 Read the Docs 테마를 적용시킨 결과물이다. 저런걸 간단하게 얻을 수 있다!
아래로는 간단한 사용법이다.
편한 시간에 작성할 것이고, 리눅스 환경이 굳이 필요하지도 않기 때문에 윈도우 환경으로 진행했다.
[ 환경 ]
Windows 10
Python3.9 + pip
먼저 cmd창을 열어서 pip로 sphinx 도구를 다운로드 받는다.
|
pip install sphinx
|
설치가 완료되면 스타트한다.
|
sphinx–quickstart
|
|
>sphinx–quickstart
Welcome to the Sphinx 4.0.3 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: 프로젝트 이름
> Author name(s): 제작자 이름
> Project release []: 릴리즈(버전)
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx–doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ko
Creating file [DIR]\source\conf.py.
Creating file [DIR]\source\index.rst.
Creating file [DIR]\Makefile.
Creating file [DIR]\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file C:\[DIR]\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where “builder” is one of the supported builders, e.g. html, latex or linkcheck.
|
처음에 y/n를 묻는 것은 source 폴더와 build 폴더를 나눌지 묻는건데 처음에는 일단 나누는 것을 추천한다.
그리고 적은 이름이나 버전은 이후 만들어지는 conf.py 파일에서 언제든지 수정이 가능하니 이름짓기로 시간을 허비하지 않아도 된다.
이렇게 하면 현재 위치에 source 폴더와 build 폴더가 생긴다.
우리가 수정해야 할 코드는 source 폴더 안에 있는데 수정은 다음에 하도록 하고 먼저 빌드를 해보겠다.
|
sphinx-build -b html .\source .\build
|
HTML문서로 만들 것이고 원본 소스는 source 폴더에, 결과물은 build 폴더에 저장한다는 내용이다.
만들어진 파일은 build 폴더에 가서 index.html 파일을 실행해보면 바로 확인이 가능하다.
처음 탬플릿을 보면 내가 왜 이걸 만들었는가 하는 생각이 들겠지만 다양한 탬플릿이 공개되어있다.
https://sphinx-themes.org/
여기에서는 앞서 소개했던 Read the Docs를 적용해보겠다.
|
pip install sphinx_rtd_theme
|
이렇게 테마를 설치해주고 source 폴더의 conf.py 파일을 수정해준다.
|
57
|
html_theme = ‘sphinx_rtd_theme’
|
이제 다시 빌드해주면 끝이다!
rst 문법이나 기타 작성법은 나중에 시간이 되면 정리해서 올려야겠다.