[Sphinx] 시작하기 (문서 레이아웃 만들기) (2)

문서 레이아웃 만들기

 

명령줄에서 다음 명령을 실행한다.

 

 $ sphinx-quickstart docs

 

그러면 docs폴더 안에 프로젝트에 대한 기본 디렉토리 및 구성 레이아웃을 만드는 데 필요한 일련의 질문이 표시된다. 계속하려면 다음과 같이 각 단계를 거친다.

 

> Separate source and build directories (y/n) [n]: " "(따옴표 제외)라고 쓰고 y를 누른다 Enter. > Project name: " "(따옴표 제외)라고 쓰고 Lumache를 누른다 Enter. > Author name(s): " "(따옴표 제외)라고 쓰고 Graziella를 누른다 Enter. > Project release []: " "(따옴표 제외)라고 쓰고 0.1를 누른다 Enter. > Project language [en]: 비워두고 (기본값, 영어) 를 누른다 Enter.

 

마지막 단계 후에 docs의 다음 내용이 포함된 새 디렉터리가 표시된다.

 

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

 

각 파일의 목적은 다음과 같다.

 

build/ : 렌더링된 문서를 보관할 빈 디렉토리 (현재). make.bat 그리고 Makefile : 콘텐츠 렌더링과 같은 일부 일반적인 Sphinx 작업을 단순화하는 편리한 스크립트이다. source/conf.py Sphinx : 프로젝트의 구성을 담고 있는 Python 스크립트. 여기에는 sphinx-quickstart에 지정한 프로젝트 이름 및 release와 일부 추가 구성 키가 포함된다. source/index.rst : 시작 페이지 역할을 하고 "목차 트리" (또는 toctree)의 루트를 포함하는 프로젝트 의 루트 문서다.

 

이 부트스트랩 단계 덕분에 처음으로 문서를 HTML로 렌더링하는 데 필요한 모든 것을 이미 갖추었다. 그렇게 하려면 다음 명령을 실행한다.

 

sphinx-build -b html docs/source/ docs/build/html

 

마지막으로 docs/build/html/index.html 브라우저에서 연다. 다음과 같이 표시되어야 한다.

 

 

https://www.sphinx-doc.org/en/master/tutorial/getting-started.html#creating-the-documentation-layout

Getting started — Sphinx documentation