sphinx로 시작하는 문서 빌드와 외국어 버전 관리

Transcript

1. Sphinx۽ द੘ೞח ޙࢲ ઁ੘җ ৻Ҵয ߡ੹ ҙܻ ӣ૑਷
2. ӣ૑਷ ӝࣿҗ ੋрਸ ੒ח ੌী 
 ҙब੉ ݆णפ׮. (੹) ֎੉ߡ Clova AI ੋఢ 
 - Technical writing
 - UX research
3. ݾ಴ • ޙࢲ ઁ੘ بҳ Sphinx ౵ঈೞӝ • য়ט ׼੢ Sphinx ޙࢲܳ ઁ੘ೞח ߑߨ ੉೧ೞӝ • Sphinx ޙࢲ ઁ੘ Ҋ޹೧ࠁӝ
 
 => ౚషܻ঴ + ҙ۲ ੉ঠӝ
4. ೡ ੉ঠӝ 1. Sphinxܳ ঌইࠇद׮! 2. ࡅܰѱ ݅٘ח Sphinx ޙࢲ 3. ޙࢲ ղਊ ଻਋ӝ 4. ৻Ҵয ޙࢲ ઁ੘ 5. ݃ޖܻ
5. ઱੄ Macਸ ӝળਵ۽ ੘ࢿೞ৓णפ׮.. ƃƃ..
6. Sphinxܳ ঌইࠇद׮!
7. BSD ۄ੉ࣃझܳ о૓ ޙࢲ ઁ੘ بҳ • BSD ۄ੉ࣃझ = ੗ਬ܂ѱ ߸ഋ оמ, 
 ࢚স੸ ࢎਊ оמ • য়೑ࣗझ۽ ܻࠛӝب ೤פ׮. • ಞೞѱ ޙࢲܳ ٜ݅ ࣻ ੓׹פ׮ :)
8. ౵੉ॆ ޙࢲ ઁ੘ਸ ਤ೧ ୊਺ ٜ݅য઎णפ׮. Table of Contents(TOC) Contents
9. sphinx-themes.org ׮নೠ ప݃о ੓যਃ! য়ט਷ sphinx_rtd_theme ઺ब
10. Sphinx੄ ੢੼ • ׮নೠ Output ನݘ : HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
 • ҅கഋ ҳઑ : ޙࢲ উ੄ ޙࢲ ੘ࢿ • ௏٘ ೞ੉ۄ੉౟ : ঱যী ٮۄ ъઑ ಴द оמ • Extension ࢎਊ : ^^ http://www.sphinx-doc.org/en/master/
11. ࡅܰѱ ݅٘ח Sphinx ޙࢲ
12. Sphinx ޙࢲ ݅٘ח ߨ 1) Docker ஶప੉ց ٜ݅ӝ 2) Docker উী 
 pip install sphinx-rtd-theme
 pip install sphinx-intl 3) sphinx-quickstart -> [y] ࢶఖ 4) make html೧ࢲ ޙࢲ ࠽٘
13. 1) Docker ஶప੉ց হযب ࠽٘ח оמ. ޙࢲ ഈসਸ ૓೯ೞ׮ ࠁݶ ߡ੹੉ Ԙੌ ࣻب ੓ਵ޲۽ 
 ݅٘ח Ѧ ୶ୌ! IUUQTXXXEPDLFSDPN
14. 1) Docker ஶప੉ց // بழ ٜ݅ӝ
 // -itd : interactive mode, dockerܳ onਸ ೞח ࢚క ٜ݅ӝ
 docker run -itd --name new-docs -v $(pwd):/app python:3.5 bash // بழ ੽ࣘೞӝ
 docker exec -it new-docs bash
 cd app/ // بழ աоӝ
 exit ఠ޷օী ੗઱ ॳח Docker ݺ۸য new-docs < ਗೞח ੉ܴਵ۽ ߸҃ೞࣁਃ!
15. 1) Docker ஶప੉ց // بழ ੤द੘, ઺૑
 docker start new-docs
 docker stop new-docs // ځ੓ח(?) بழ ݾ۾ ഛੋ docker ps // લ਷ Ѫө૑ ࠁৈષ docker ps -a // بழ ࢏ઁೞӝ docker rm new-docs(ژח docker id) ఠ޷օী ੗઱ ॳח Docker ݺ۸য(2)
16. 2) pip install pip install sphinx-rtd-theme => rtd theme۽ sphinx ޙࢲ ੘ࢿ pip install sphinx-intl => ৻Ҵয ߡ੹ ઁ੘ਊ
17. 2) pip install // ޙࢲܳ ҙܻೞח ಫ؊ܳ ٜ݅Ҋ, Ӓ ಫ؊ উীࢲ بழী 
 ੽ࣘ೤פ׮.
 mkdir new-docs
 cd new-docs
 docker exec -it new-docs bash
 cd app/ // sphinxܳ ࢸ஖೤פ׮. pip install sphinx-rtd-theme pip install sphinx-intl
18. 3) sphinx-quickstart -> [y] ࢶఖ //ӝࠄ ޙࢲ ࢤࢿ sphinx-quickstart - yܳ ੑ۱ 
 => ࣗझ ౵ੌҗ ࠽٘ ౵ੌਸ ٮ۽ ҙܻೞח ѱ ಞܻ.
 - աݠ૑ח ਗೞח؀۽. - Language ࢸ੿ਸ ਗೠ׮ݶ ೠҴযח ko ੑ۱ - config.py ౵ੌীࢲ html_theme = ‘sphinx_rtd_theme’
 ۽ ߄Լસפ׮. http://www.sphinx-doc.org/en/master/usage/quickstart.html
19. 4) make html۽ ޙࢲ ࠽٘ // ޙࢲ ࠽٘ make build makeח ই઱ ੗઱ ॳѱ ؼ ݺ۸য
20. ૞ਖ਼! ޙࢲо ৮ࢿ!
21. +) ਢী ৢܻӝ(ࡅܰѱ github) .nojekyll < ౵ੌ ٜ݅যঠ ੿࢚੸ਵ۽ ࠁ੐ ࠽٘ ղਊ݅ ৢܻݶ మ೒݁੉ ӵ૑פ ઱੄.
22. ޙࢲ ղਊ ଻਋ӝ
23. ٜযח ࠌա, reStructuredText ޙߨ • য۵૑ ঋইਃ :) .mdی ࠺तೞѱ ࢤпೞݶ ؽ • .rst۽ աয়ח ౵ੌী ղਊ ੘ࢿ • reST ޙߨ੉ۄҊب ࠛܿ
24. ӝࠄ੸ੋ reST ޙߨ https://sphinx-rtd-theme.readthedocs.io/en/ stable/demo/demo.html
25. ӝࠄ੸ੋ reST ޙߨ **strong** *Italic* :guilabel:`Dataset` ``model`` .. figure:: ./static/prepare.png :align: center :scale: 30 % strong Italic
26. ӝࠄ੸ੋ reST ޙߨ :ref:`dataset<dataset()>` .. _dataset:
27. ӝࠄ੸ੋ reST ޙߨ
28. ৻Ҵয ޙࢲ ٜ݅ӝ
29. ৻Ҵয ޙࢲ, ৵ ٜ݅যঠ ೡөਃ? • Ӗ۽ߥೠ ࢎਊ ࢸݺࢲо ೙ਃೞ׮ݶ? 
 Ӓؘ۠ ೠҴ ࢎਊ੗о ݆ইࢲ ೠҴযܳ ॳҊ र׮ݶ? • ࢎղ/Ӓܛ ղ ৻Ҵੋ ݯߡܳ ਤೠ ׮নࢿ
 
 => ੌױ ৔য۽ ݅ٚ׮Ҋ ࢤп೧ࠇद׮.
30. Internationalization ߑߨ Localization੉ۄҊب ೤פ׮! https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
31. 3ױ҅ җ੿ .rst => .pot => .po, .mo (1) (2) (3)
32. 3ױ҅ җ੿ //.rst ౵ੌਸ pot ౵ੌ۽ build/gettextۄח ਤ஖ী ߸ജ 
 sphinx-build -b gettext ./source build/gettext // build/gettext ਤ஖ী ੓ח pot ౵ੌਸ locale/en_US/ LC_MESSAGESۄח ਤ஖ী po ౵ੌ۽ ߸ജ
 sphinx-intl update -p build/gettext -l en_US // locale/en_US/LC_MESSAGES ਤ஖ী ੓ח po ౵ੌਸ build/html/en_US ਤ஖ী html۽ ߸ജ, mo ౵ੌ੉ ࢤࢿؽ.
 sphinx-build -b html -D language=en_US ./source build/html/en_US (1) (2) (3) https://docs.readthedocs.io/en/stable/localization.html
33. 3ױ҅ җ੿ //.rst ౵ੌਸ pot ౵ੌ۽ build/gettextۄח ਤ஖ী ߸ജ 
 sphinx-build -b gettext ./source build/gettext // build/gettext ਤ஖ী ੓ח pot ౵ੌਸ locale/en_US/ LC_MESSAGESۄח ਤ஖ী po ౵ੌ۽ ߸ജ
 sphinx-intl update -p build/gettext -l en_US // locale/en_US/LC_MESSAGES ਤ஖ী ੓ח po ౵ੌਸ build/html/en_US ਤ஖ী html۽ ߸ജ, mo ౵ੌ੉ ࢤࢿؽ.
 sphinx-build -b html -D language=en_US ./source build/html/en_US (1) (2) (3) https://docs.readthedocs.io/en/stable/localization.html ਗೞח ঱যܳ աఋղݶ OK! EN, en, US ݽف оמ
34. .po ౵ੌী ڣٯڣٯ ৔য ߣ৉ .rst ౵ੌী ڣٯڣٯ ೠҴয ੘ࢿ (ബਯ੸੉ۄ ࢤпೞח) ઁ੘ җ੿ (1) (2) (3) 
 make html
 sphinx-build -b gettext ./source build/gettext
 sphinx-intl update -p _build/gettext -l en_US 
 
 
 
 sphinx-build -b html -D language=en_US ./source build/html/en_US 1. 2. 3. 4. 5. 6.
35. Makefileী ݺ۸য customizing Makefile ౵ੌী make _____ ഋधਵ۽ ઁ੘
36. Makefileী ݺ۸য customizing Makefile ౵ੌী make _____ ഋधਵ۽ ઁ੘ .PHONY: intlpo intlpo: $(SPHINXBUILD) -b gettext . $(BUILDDIR)/gettext $(SPHINXINTL) update -p $(BUILDDIR)/gettext -l en_US @echo @echo "Build finished. The .po file is updated." # You can set these variables from the command line. SPHINXBUILD = sphinx-build BUILDDIR = _build SPHINXINTL = sphinx-intl
37. ੗߄झ௼݀౟ ܻ׮੉۩౟ • ࠳ۄ਋੷ ࢸ੿ী ٮۄ ೠҴযо ইפݶ ৔য۽ ࠁղ Ҋ, ೠҴযݶ ೠҴয۽ ࠁղӝ
38. ੗߄झ௼݀౟ ܻ׮੉۩౟
39. ੗߄झ௼݀౟ ܻ׮੉۩౟ <script type="text/javascript"> function getLang(){ var userLang = navigator.language || navigator.userLanguage; return userLang; } var lang = getLang(); if(lang != ("ko-KR" || "ko")){ lang = "en_US"; } else{ lang = "ko_KR"; } var meta = document.getElementsByTagName('meta')[0]; meta.setAttribute("content","0; url=_build/html/"+lang+"/index.html"); meta.setAttribute("http-equiv","refresh"); </script>
40. ߣ৉੄ נ • ৌब൤ ೠ઴ঀ ֍णפ׮! ROI উաয়૑݅ Տӝ੓ѱ ೧ ࠇद׮! Transifexۄח ోب ੓਺.
 
 
 
 
 
 • ೠҴয(ਗޙ)ਸ Ҋ஖ݶ .po ౵ੌী 
 #,fuzzy੉ աয়ݶࢲ ৔য(ߣ৉ޙ)о ӵ૑ח Ѫ ઱੄! ৈӝী ߣ৉
41. ݃ޖܻ
42. Sphinx ഝਊ ߑউ • ѐߊ੗ٜ р੄ ղࠗ ࣗా ਊب • ࢎਊ੗ ҕѐ ਊب
43. Pandas | Python ؘ੉ఠ ࠙ࢳ ۄ੉࠳۞ܻ https://pandas.pydata.org/pandas-docs/stable/
44. ֢࣌੉ ؊ જਸ ࣻب.. оѺ੉ ࠗ׸غҊ, ખ ؊ ݧઉࠁ੉Ҋ र׮ݶ Sphinx ॳࣁਃ :)
45. хࢎ೤פ׮! Email | xjpassion@naver.com FB | /jieun.kim0413