많은 Python 패키지 및 라이브러리 문서들은 일반적으로 GitHub 등에서 사용하는 Markdown 문법이 아닌, rst (Restructured Text) 문법을 사용하여 작성이 이루어지며, Sphinx 라이브러리를 활용하여 html 또는 pdf로 build하여 해당 패키지 및 라이브러리 문서화를 관리하고 있습니다. 본 발표에서는 rst가 무엇인지부터 시작하여, rst와 관련된 기본 문법을 통해 html 또는 pdf로 어떻게 생성할 수 있는지 각 단계별로 살펴봄으로써 Python 문서화가 이루어지는 전반적인 과정을 먼저 살펴봅니다. 이후, Python을 활용하고 있는 OpenStack 프로젝트에서 문서를 code처럼 관리하기로 결정한 이후, rst 기반으로 설치 가이드 등을 작성하고 Sphinx 및 별도 theme를 적용하여 html 및 pdf를 생성하여 활용하는 실 활용 사례를 같이 살펴보고자 합니다.

1. Rst와 함께하는 Python 문서 작성
& OpenStack 문서 활용 사례
최영락 (ianyrchoi@gmail.com)

2. 목차
▪ 코딩 vs. “문서” 작성
▪ Rst (RestructuredText)
• 개요 및 역사
• 짧은 문법 소개
• Sphinx
▪ Case: OpenStack에서의 문서 활용 사례 with rst
▪ 마무리

3. I. 코딩 vs. ”문서” 작성

4. 언어 (Languages)
• 설계/개발/QA • 말하기/읽기/쓰기

5. 코딩 컨벤션

6. 문서에도 필요한 컨벤션
▪ (문서 파일 형식)

7. 문서에도 필요한 컨벤션
▪ 텍스트 파일: 협업!

8. 문서에도 필요한 컨벤션
▪ 어떤 형식으로 문서에 담을 것인가?

9. 문서에도 필요한 컨벤션
▪ (예시: 위키 포맷)

10. II. Rst (RestructuredText)

11. Rst (RestructuredText) 개요
▪ 텍스트 파일입니다
▪ 확장자: .rst (영어 첫 문자를 대문자로 써야 해서 ”Rst”로…)
▪ “RestructuredText” 1개 단어입니다
• 띄어쓰지 않습니다: “Restructured Text”  X
• 줄임말: RST / Rst / rst / ReST / reST

12. Rst (RestructuredText) 역사
▪ http://docutils.sourceforge.net/docs/ref/rst/introduction.html
(무책임한 스샷)

13. Rst (RestructuredText) 역사
▪ 2002년 4월 포맷이 처음 제정됨
• 1992년 Setext (Structure Enhanced Text)  StructuredText (?) 영향을 받아
만들어졌다고 함
▪ Python 문서화를 고민하던 Python Doc-SIG에서 2000년 초반부터
본격 논의를 시작하여 문서 규격을 정의
▪ PEP-287: https://www.python.org/dev/peps/pep-0287/

14. 짧은 문법 소개

15. Sphinx
▪ Rst 문서를 HTML, PDF 등으로 변환 가능
▪ 폴더 구조 및 conf.py 등을 잘 정의해야 함 (템플릿 있어요!)

16. III. OpenStack에서의 문서 활용 사례
with rst

17. 잠깐: OpenStack이란
▪ 클라우드 환경에서 컴퓨팅 자원과 스토리지 인프라를 셋업하고
구동하기 위해 사용하는 오픈 소스 소프트웨어 프로젝트의 집합
▪ Python으로 구현, Apache 라이선스

18. OpenStack 문서화 프로젝트
▪ https://docs.openstack.org

19. OpenStack 참여 Python developer & contributor (예)
▪ Richard Jones
▪ Doug Hellmann

20. OpenStack: 처음부터 rst를 쓰지는 않았습니다
▪ (XML 기반 DocBook)

21. Rst로 문서 마이그레이션 성공
▪ Sphinx로 문서 생성
• HTML output

22. Rst: 프레젠테이션 형식 지원
▪ Hydroglyph

23. Rst: PDF 형식 지원
▪ Latex & PDF

24. Doc8: PEP-8처럼 사용
▪ 1줄에 80자 넘기지 않기
▪ …

25. IV. 마무리

26. Rst로 작성해 봅시다
▪ README.md도 좋지만 README.rst도 해 봅시다 ☺