Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

[Pycon KR 2017] Rst와 함께하는 Python 문서 작성 & OpenStack 문서 활용 사례

2,522 views

Published on

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

[Pycon KR 2017] Rst와 함께하는 Python 문서 작성 & OpenStack 문서 활용 사례

  1. 1. Rst와 함께하는 Python 문서 작성 & OpenStack 문서 활용 사례 최영락 (ianyrchoi@gmail.com)
  2. 2. 목차 ▪ 코딩 vs. “문서” 작성 ▪ Rst (RestructuredText) • 개요 및 역사 • 짧은 문법 소개 • Sphinx • Rst 장점 & 단점 ▪ Case: OpenStack에서의 문서 활용 사례 with rst ▪ 마무리
  3. 3. I. 코딩 vs. ”문서” 작성
  4. 4. 언어 (Languages) • 설계/개발/QA • 말하기/읽기/쓰기
  5. 5. 코딩 컨벤션
  6. 6. 문서에도 필요한 컨벤션 ▪ (문서 파일 형식)
  7. 7. 문서에도 필요한 컨벤션 ▪ 텍스트 파일: 협업!
  8. 8. 문서에도 필요한 컨벤션 ▪ 어떤 형식으로 문서에 담을 것인가?
  9. 9. 문서에도 필요한 컨벤션 ▪ (예시: 위키 포맷)
  10. 10. II. Rst (RestructuredText)
  11. 11. Rst (RestructuredText) 개요 ▪ 텍스트 파일입니다 ▪ 확장자: .rst (영어 첫 문자를 대문자로 써야 해서 ”Rst”로…) ▪ “RestructuredText” 1개 단어입니다 • 띄어쓰지 않습니다: “Restructured Text”  X • 줄임말: RST / Rst / rst / ReST / reST
  12. 12. Rst (RestructuredText) 역사 ▪ http://docutils.sourceforge.net/docs/ref/rst/introduction.html (무책임한 스샷)
  13. 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. 14. 짧은 문법 소개 ▪ https://gist.github.com/ianychoi/31a00efd06c9a855bfbc15de6ec8d117
  15. 15. Sphinx ▪ Rst 문서를 HTML, PDF 등으로 변환 가능 ▪ 폴더 구조 및 conf.py 등을 잘 정의해야 함 (템플릿 있어요!)
  16. 16. Sphinx로 rst 기반 문서 생성하기 ▪ Sphinx-quickstart • conf.py 파일 및 디렉토리 구조, Makefile 등 생성 도와줌
  17. 17. Rst 장점 & 단점 ▪ 장점 • Semantic 반영되어 있음 ✓텍스트만을 보고 유추 가능 • Python extension이 많음 • … ▪ 단점 • (로고가 없다) • Markdown과 비교할 때, 덜 대중적임 ✓예: Markdown + reveal.js vs. rst2html5 • …
  18. 18. III. OpenStack에서의 문서 활용 사례 with rst
  19. 19. 잠깐: OpenStack이란 ▪ 클라우드 환경에서 컴퓨팅 자원과 스토리지 인프라를 셋업하고 구동하기 위해 사용하는 오픈 소스 소프트웨어 프로젝트의 집합 ▪ Python으로 구현, Apache 라이선스
  20. 20. OpenStack 문서화 프로젝트 ▪ https://docs.openstack.org
  21. 21. OpenStack 참여 Python developer & contributor (예) ▪ Richard Jones ▪ Doug Hellmann
  22. 22. OpenStack: 처음부터 rst를 쓰지는 않았습니다 ▪ (XML 기반 DocBook)
  23. 23. Rst기반으로 옮겨보자 ▪ (설치 가이드부터 차근차근…) • http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide- liberty-rst.html
  24. 24. Rst로 문서 마이그레이션 성공 ▪ Sphinx로 문서 생성 • HTML output ▪ 현재 모든 문서를 rst로 작성 • (심지어 spec까지도)
  25. 25. Rst: 프레젠테이션 형식 지원 ▪ Hydroglyph
  26. 26. 문서 번역: rst 형식을 고려 ▪ https://developer.ibm.com/opentech/2015/04/28/restructuredtext-markups-manuals-translation-tips/
  27. 27. Rst: PDF 형식 지원 ▪ Latex & PDF
  28. 28. Doc8: PEP-8처럼 사용 ▪ 1줄에 80자 넘기지 않기 ▪ …
  29. 29. IV. 마무리
  30. 30. Rst로 작성해 봅시다 ▪ README.md도 좋지만 README.rst도 해 봅시다 ☺
  31. 31. OpenStack: 문서화 & 번역팀 PTL + @ Documentation team former PTL (Project Technical Leader) I18n (Internationalization) team former PTL
  32. 32. 감사합니다! Thank you!

×