Sphinxcon JP 2014 presentation: SphinxとLaTeXで作る英文マニュアル

A Japanese presentation on publishing an English manual in Sphinx and LaTeX. Example repository avalable at: https://github.com/jj1bdx/sphinxconjp2014-examples

Transcript

1. SphinxͱLaTeXͰ࡞ ΔӳจϚχϡΞϧ Kenji Rikitake / SphinxConJP 2014 1
2. ྗ෢ ݈࣍ ʢΓ͖͚ͨ ͚Μ͡ʣ ྗ෢݈ٕ࣍ज़࢜ࣄ຿ॴॴ௕ @jj1bdx http://rikitake.jp/ SphinxCon JP 2014 26-OCT-2014 Shibuya-ku, Tokyo, Japan Kenji Rikitake / SphinxConJP 2014 2
3. ࣗݾ঺հ —Sphinxར༻ྺ: ൒೥ —LaTeXར༻ྺ: 21೥ —1994೥ʹLaTeXͰ೔ຊ ޠͷຊΛॻ͖·ͨ͠ —2004೥ʹLaTeXͰӳޠ ͷത࢜࿦จΛॻ͖·ͨ͠ —Sphinxॳ৺ऀͰ͢ Kenji Rikitake / SphinxConJP 2014 3
4. LaTeXʢϥςοΫʣͬͯԿ? —૊൛γεςϜTeXͷ্ͷϚʔΫΞοϓݴޠ —30೥ͷྺ࢙ʢ೔ຊޠԽ΋΄΅ಉ͡ʣ —࿦จ΍Ϩϙʔτʹ͸ඞਢ —ઐ໳ॻΛத৺ʹຊͷग़൛࣮੷΋ଟ਺ —ӳจʢ࿨จ΋ʣͷ૊൛͸Wordͱ͸ൺֱʹ ͳΒͳ͍͘Β͍ඒ੍͔ͭ͘͠ޚ͠΍͍͢ —ࣗ༝ͳϥΠηϯεͰར༻Ͱ͖Δ Kenji Rikitake / SphinxConJP 2014 4
5. LaTeXͷจষͷྫ %%% Source code quoted from: %%% Rikitake, K., Suzuki, T., and Nakao, K.: %%% DNS Security: Now and The Future, %%% IEICE Technical Report ISEC2007-1, pp. 3-8 (2007). \begin{itemize} \item deletion of the NS RRs by the expiration of DNS registry subscription~\footnote{On May 2005, \url|e-ontap.com|, which had the authoritative servers running for \url|visa.co.jp| and other related domains, was found non-existent. Suzuki~\cite{tss-visa} took over the control of \url|e-ontap.com| to prevent further possible domain abuse and hijacking.}; \item NS RRs are not directed to the appropriate servers; and \item A/AAAA RRs do not point the correct IP addresses of the servers listed in the NS RRs. \end{itemize} Kenji Rikitake / SphinxConJP 2014 5
6. LaTeXͷ૊൛ͷྫ(1/2) ຊจ Kenji Rikitake / SphinxConJP 2014 6
7. LaTeXͷ૊൛ͷྫ(2/2) ٭஫ Kenji Rikitake / SphinxConJP 2014 7
8. Sphinx͔ΒLaTeXΛ࢖͏ར఺ —ReSTͰେ෦෼͕౷ҰͰ͖Δ —HTMLͱPDFΛಉ͡ιʔε͔Β࡞ΕΔ —ιʔεͷຒΊࠐΈָ͕ (code-block) —URLͷຒΊࠐΈָ͕ ʢࣗಈม׵ʣ —ਤͷຒΊࠐΈ΋ָ (image) —LaTeX࢖͍ͷਓʹ͸σόοάָ͕(?) Kenji Rikitake / SphinxConJP 2014 8
9. SphinxͰͲΜͳϚχϡΞϧΛॻ͍͔ͨ —גࣜձࣾηΩϡΞεΧΠɾςΫϊϩδʔ ༷ͷґཔʹΑΔಉࣾͷ೔ຊޠจॻ͔Βӳ ޠจॻ΁ͷ຋༁ —HTML൛จॻ࡞੒͕࠷༏ઌɼPDF͸2൪໨ —JavaɼPHPɼͦͷଞιʔείʔυଟ਺ —ଟ਺ͷਤ൛(100ຕ௒) —಺༰͸ඇެ։ͷͨΊׂѪ Kenji Rikitake / SphinxConJP 2014 9
10. ϚχϡΞϧͷαϯϓϧ —…ͱ͸͍͑ɼαϯϓϧ͕ͳ͍ͱ͕͢͞ʹ આ໌͸೉͍͠ͷͰ࡞Γ·ͨ͠ —https://github.com/jj1bdx/ sphinxconjp2014-examples/ Kenji Rikitake / SphinxConJP 2014 10
11. SphinxΛ࢖ͬͯ΋ָʹͳΒͳ͍͜ͱ —຋༁ͷۤ࿑͸ಉ͡ —ਤ൛Λ࡞Δۤ࿑͸ಉ͡ —ߍਖ਼ͷۤ࿑͸ಉ͡ —ཁ͢Δʹ඼࣭Λ্͛Δۤ࿑͸ಉ͡ —େࣄͳͷ͸্هͷ࡞ۀʹΑΓଟ͘ͷ࣌ؒ ΛׂΓ౰ͯΔ͜ͱͰɼͦͷͨΊʹSphinx ΍LaTeXΛ࢖͏ Kenji Rikitake / SphinxConJP 2014 11
12. ؔ࿈ΩοτͷΠϯετʔϧ —TeXLive 2014 (MacͳΒMacTeX)Λ࢖͏ —LaTeXͦͷ΋ͷ͸೔ຊޠରԠࡁΈ —೔ຊޠͷࡉ͔͍tips͸Ԟଜ੖඙ઌੜͷTeX Wiki ʹ http://oku.edu.mie-u.ac.jp/ ~okumura/texwiki/ —pLaTeX͕ಈ͚͹·ͣ͸४උ׬ྃ Kenji Rikitake / SphinxConJP 2014 12
13. LaTeXͷࢀߟॻ —Ԟଜ੖඙ஶʦվగୈ6 ൛ʧLaTeX2e ඒจॻ࡞ ੒ೖ໳ʢٕज़ධ࿦ࣾʣ —http://gihyo.jp/book/ 2013/978-4-7741-6045- 0 —ஶऀʹΑΔ௥Ճ৘ใ: http://oku.edu.mie- u.ac.jp/~okumura/ bibun6/ Kenji Rikitake / SphinxConJP 2014 13
14. LaTeXܦ༝ͷPDFੜ੒ —make latexpdfja Ͱ _build/latex/ ͷԼʹҰࣜͰ͖Δ(Sphinx 1.2.3)ͷͰɼͦ ͜Ͱ͞Βʹmake͢ΔͱPDF͕Ͱ͖Δ —ਤ͸extractbbͰαΠζ৘ใΛऔಘͯ͠ ͓͘ʢGNU parallelͰߴ଎ԽͰ͖Δʣ parallel extractbb ::: *.jpg *.png Kenji Rikitake / SphinxConJP 2014 14
15. HTML༻index.rstͷઃఆ .. toctree:: license .. toctree:: :maxdepth: 4 :numbered: 3 chapter1 chapter2 Kenji Rikitake / SphinxConJP 2014 15
16. LaTeX༻index.rstͷઃఆ(1/2) .. raw:: latex %%% %%% Disable all chapter/section numbering \setcounter{secnumdepth}{-2} %%% .. toctree:: license Kenji Rikitake / SphinxConJP 2014 16
17. LaTeX༻index.rstઃఆ(2/2) .. raw:: latex %%% %%% Max toctree level: 1.2.3 \setcounter{secnumdepth}{2} %%% Reset all counters \setcounter{chapter}{0} \setcounter{section}{0} \setcounter{subsection}{0} %%% .. toctree:: chapter1 chapter2 Kenji Rikitake / SphinxConJP 2014 17
18. LaTeX༻conf.pyͷઃఆ(1/3) latex_elements = { # The paper size ('letterpaper' or 'a4paper'). 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. 'classoptions': ',dvipdfmx', 'babel': r'\usepackage[english]{babel}', 'fncychap': '', 'fontpkg': r'\usepackage{amsmath,txfonts}', Kenji Rikitake / SphinxConJP 2014 18
19. LaTeX༻conf.pyͷઃఆ(2/3) # latex_elementsͷఆ͕ٛଓ͘ 'preamble': r''' \hypersetup{colorlinks=false} \setcounter{tocdepth}{3} %%% see sphinxmanual.cls \makeatletter % needs this to enable @-mark % aligned: 7.6em, 0em: no indent for % multiple index lines \renewcommand*\l@subsubsection{% \@dottedtocline{3}{11.1em}{0em}} \renewcommand{\@pnumwidth}{2em} \renewcommand{\@dotsep}{1.5} \makeatother % needs this to disable @-mark ''', } Kenji Rikitake / SphinxConJP 2014 19
20. LaTeX༻conf.pyͷઃఆ(3/3) latex_documents = [ ('index-latex', 'LaTeXtestdocforSphinxConJP2014.tex', u'LaTeX test doc for SphinxConJP 2014 Documentation', u'Kenji Rikitake', 'manual'), ] Kenji Rikitake / SphinxConJP 2014 20
21. Sphinxͷઃఆ͔ΒLaTeXιʔε΁ͷ൓ө ൓ө͞ΕΔ৔ॴʹ஫ҙ͕ඞཁ %%% conf.pyͷpreamble͸͜͜ \begin{document} ... \maketitle \tableofcontents %%% licenseͷલʹॻ͍ͨrawͷ಺༰ % license.rstͷத਎ %%% chapter1,2ͷલʹॻ͍ͨrawͷ಺༰ % chapter*.rstͷத਎͕ଓ͘ \end{document} Kenji Rikitake / SphinxConJP 2014 21
22. SphinxͷLaTeXॲཧͰݟΔ΂͖৔ॴ —texinputs/sphinxmanual.cls —writers/latex.py —ಛʹ default_elements —ઃఆͷ্ॻ͖͸conf.pyͷpreambleͰ —@͕ೖΔͱ͖͸\makeatletterͱ \makeatotherͰ͘͘Δ Kenji Rikitake / SphinxConJP 2014 22
23. ੍ݶࣄ߲: ෳ਺ߦ/ྻηϧͷද͸දࣔෆՄ —Sphinx 1.2.2Ͱ͸LaTeXίϯύΠϧΤϥʔ —μϝͳྫ +--------------------+----------------+ | 2 rows and 2 cols | 1 row x 3 cols | | +----+-----+-----+ | | A | B | C | +---+----------------+----+-----+-----+ | 1 | 2 | 3 | 4 | 5 | +---+----------------+----+-----+-----+ Kenji Rikitake / SphinxConJP 2014 23
24. ͦͷଞLaTeXιʔεੜ੒Ͱͷ஫ҙࣄ߲ —ਤදͷԣ෯͸ϖʔδຊจͷ෯͍ͬͺ͍ʹ ల։͞ΕΔʢ2ஈ૊ͷϚΫϩͰճආ?ʣ —ग़དྷ্͕Γ͸ΧϥʔʢനࠇઃఆՄʣ —࢓্Γ͸LaTeXϚΫϩ/ελΠϧϑΝΠϧ ࣍ୈˠ࡞ΓࠐΈΛ͍ͨ͠ͱ͖͸࠷ॳ͔Β શ෦ࣗલͰ༻ҙ͢Δඞཁ͕͋Δ —·ͣ͸ॳظઃఆͰ࢖͍मਖ਼͢Δͷ͕ૣಓ Kenji Rikitake / SphinxConJP 2014 24
25. ݁࿦: ཁ఺Λ΋͏Ұ౓ —Sphinx͔ΒPDFΛ࡞Δʹ͸LaTeXͷษڧ Λ͓ͯ͘͠ͱԠ༻͕ޮ͘ —Πϯετʔϧʹ͸TeXLiveΛ࢖͍·͠ΐ͏ —HTMLͱLaTeXͰ͸ϚελʔυΩϡϝϯ τ͸ผʹ࡞͓ͬͯ͘ —LaTeXੜ੒ͷৄࡉΛ஌Δʹ͸Python͕ಡ ΊΔΑ͏ʹͳ͓ͬͯ͘ͱΑ͍ Kenji Rikitake / SphinxConJP 2014 25
26. αϯϓϧ͸ͪ͜ΒͰ͢ —https://github.com/jj1bdx/ sphinxconjp2014-examples/ Kenji Rikitake / SphinxConJP 2014 26