RTD #
Find similar titles

프로젝트 문서화
프로젝트 발표
스핑크스(Sphinx)

프로젝트 문서화 #

최상위 디렉터리의 README 파일에는 해당 프로젝트의 사용자와 유지보수 담당자 모두에게 도움이 되는 일반적인 정보가 있어야 한다. 순수한 텍스트로 작성하거나, 읽기 쉬운 마크업 문서로 작성하면 된다. 문서에는 반드시 프로젝트나 라이브러리 (사용자가 이 프로젝트의 모든 것을 알고 있을 거라고 생각하면 안된다)의 목적을 설명하는 몇 줄의 글, 소프트웨어를 위한 주요 소스의 URL, 몇 가지 기본적인 신용 정보를 포함해야 한다.

LICENSE 파일은 반드시 있어야만 하고, 소프트웨어가 공개 가능한지 아닌지를 명시해야 한다.

README 안의 TODO 파일이나 TODO 부분에는 개발할 코드의 목록을 나열해야 한다.

CHANGE LOG 파일이나 README 안의 부분에는 반드시 최신 버전의 코드에서 일어난 변화에 대하여 개략적으로 소개해야 한다.

프로젝트 발표 #

프로젝트에 따라서 문서에는 아래의 것 중 몇 개를 포함하거나, 전부를 포함할 것이다.

Tutorial은 몇 가지 기본적인 사례를 좀 더 자세히 보여주어야 한다. 읽는 사람이 하나하나씩 따라가며 실제 동작하는 프로토타입을 만들 것이다.
API 참조는 보통 코드에서 생성된다. 공개적으로 가능한 모든 인터페이스, 파라미터, 반환 값을 보여주어야 한다.
Developer documentation은 잠재적인 기여자(contrubutors)를 위한 것이다. 여기에는 코딩 규약과 프로젝트의 일반적인 디자인 전략을 담을 수 있다.
Sphinx는 가장 유명한 파이썬 문서화 도구이다. 마크업 언어를 HTML, LaTex(인쇄할 수 있는 PDF 버전), 메뉴얼 페이지, 일반 텍스트 등의 포맷으로 바꿔준다. 그럴 뿐만 아니라 Sphinx 문서를 위한 Read The Docs라는 무료 호스팅 서비스가 있다.
소스 저장소에 커밋 후크를 걸어두면 문서를 자동으로 빌드하도록 설정할 수 있다.

스핑크스(Sphinx) #

실행 방법 #

Sphinx 설치
Sphinx 문법으로 파일 구성
build

1. Sphinx 설치 #

설치는 conda 나 pip 으로 다음과 같이 설치한다.

$ conda install Sphinx # Anaconda 사용 시 
$ pip install Sphinx # Anaconda 미사용 시

2. Sphinx 세팅 #

프로젝트의 최상위 디렉터리에서 docs 디렉터리를 만들어 진행한다.

$ mkdir docs
$ cd docs
$ sphinx-quickstart



Welcome to the Sphinx 4.5.0 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]: (Enter)

The project name will occur in several places in the built documentation.
> Project name: metabodb
> Author name(s): insilicogen
> Project release []: 1.0

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]: (Enter)

Creating file /Users/johuije/Desktop/project/service_metabodb/metabodb/metabosite/docs/conf.py.
Creating file /Users/johuije/Desktop/project/service_metabodb/metabodb/metabosite/docs/index.rst.
Creating file /Users/johuije/Desktop/project/service_metabodb/metabodb/metabosite/docs/Makefile.
Creating file /Users/johuije/Desktop/project/service_metabodb/metabodb/metabosite/docs/make.bat.

문서 작성 #

문서 작성을 위해서는 몇 가지 작업이 필요하다. 우선, root 폴더가 아닌, docs 폴더에서 문서들을 생성하였으므로 참조 주소를 root 폴더로 변경해야 한다. 이를 위해, docs/conf.py 를 수정해보자.

conf.py 에 들어가면 아래와 같이 주석 처리된 부분이 있는데, 이를 해제하면 된다. 그럼 절대경로가 root 폴더로 변경되어 문서 작업을 간편하게 할 수 있다.

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

추가로 테마의 경우에도 다양한 테마를 사용할 수 있다. conf.py 에서 html_theme 에 해당하는 변수를 바꾸어주면 된다.

html_theme = 'sphinx_rtd_theme'

해당 테마는 따로 설치해야 해서 아래와 같이 설치한다.

$ pip install sphinx_rtd_theme

3. Sphinx Build #

세팅 과정에서 생긴 Makefile을 이용해 빌드.

$ make html



Running Sphinx v4.5.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

위의 과정을 진행하면, 아래와 같은 구조의 디렉터리와 파일이 생성된다.

/docs/_build/html 안에 index.html이 생기게 되고, 해당 파일을 클릭하면 웹페이지를 확인할 수 있다.

문서 수정 #

문서 안의 내용을 수정하고 싶다면 docs/index.rstan id='1' class='checkOff' onclick='CorrectionLayer(1)'>rst 를 수정하면 된다. 해당 파일은 index.html에 보이는 문서 내용을 수정할 수 있다. 수정 전 내용은 아래와 같다.

Welcome to metabodb's documentation!
====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

toctree 구조를 지원하는 목차이고, Indices and tables 부터 내용을 의미한다.
rst, sphinx 문법을 통해 내용을 수정 할 수 있다.