Sphinxで 大量にドキュメントを手軽に作るための工夫/20200610-stapy-sphinx

みんなのPython勉強会#58 ( https://startpython.connpass.com/event/175451/ )での発表資料です。

概要: Sphinxは、知識や経験のインプットとアウトプットを構造化できる強力なツールです。時間が無いときは簡単な構造でメモしておき、時間が取れるときにしっかり構造化してあげることで、自分の暗黙的な知識や物の見方がみるみる構造化されていきます。
日本UNIXユーザ会 2010年12月勉強会「ドキュメントを作りたくなってしまう魔法のツール Sphinx」(講師: 渋川さん、山口さん、清水川さん)をきっかけにSphinxを使いはじめ、年間数千の構造化ドキュメントを書くなかでやってきた「Sphinxを使う上での工夫」についてお話しします。

(運用設計ラボ合同会社 波田野裕一)

Transcript

1. Operation Lab ӡ༻ઃܭϥϘ ӡ༻ઃܭϥϘ߹ಉձࣾ 4QIJOYͰ
   େྔʹυΩϡϝϯτΛखܰʹ࡞ΔͨΊͷ޻෉ 1  ΈΜͳͷ1ZUIPOษڧձ
   
   γχΞΞʔΩςΫτ
   ೾ా໺
   ༟Ұ
2. ֓ཁ 4QIJOY͸ɺ஌ࣝ΍ܦݧͷΠϯϓοτͱΞ΢τϓοτΛߏ଄ԽͰ͖Δ ڧྗͳπʔϧͰ͢ɻ͕࣌ؒແ͍ͱ͖͸؆୯ͳߏ଄ͰϝϞ͓͖ͯ͠ɺ ͕࣌ؒऔΕΔͱ͖ʹ͔ͬ͠Γߏ଄Խͯ͋͛͠Δ͜ͱͰɺࣗ෼ͷ҉໧ తͳ஌ࣝ΍෺ͷݟํ͕ΈΔΈΔߏ଄Խ͞Ε͍͖ͯ·͢ɻ
   ೔ຊ6/*9Ϣʔβձ
   ೥݄ษڧձʮυΩϡϝϯτΛ࡞Γͨ͘ ͳͬͯ͠·͏ຐ๏ͷπʔϧ
   4QIJOYʯ ߨࢣ
   ौ઒͞Μɺࢁޱ͞Μɺਗ਼ ਫ઒͞Μ Λ͖͔͚ͬʹ4QIJOYΛ࢖͍͸͡Ίɺ೥ؒ਺ઍͷߏ଄Խυ ΩϡϝϯτΛॻ͘ͳ͔Ͱ΍͖ͬͯͨʮ4QIJOYΛ࢖͏্Ͱͷ޻෉ʯʹ ͍͓ͭͯ࿩͠͠·͢ɻ Operation Lab ӡ༻ઃܭϥϘ 2
3. Operation Lab ӡ༻ઃܭϥϘ ࢲͱӡ༻खॱॻ 3 ‣ ೥୅લ൒
   ໷ؒ࡞ۀ࣌ͷࣗ෼͕৴͡ΒΕͳ͍ͷͰɺ ट͔ΒԼͰ࣮ߦͰ͖ΔखॱॻΛ࡞੒
   ‣ ೥୅ޙ൒
   खॻ͖9.-
   
   94-5
   YTMUQSPD ͰΠϯ ΫϧʔυՄೳͳखॱॻΛ࡞੒
   ೥ఔ౓Ͱ࠳ં
   ‣ ೥
   4QIJOYͱग़ձ͍ɺखॱॻͷߏ଄ԽΛਐΊΔɻ
   ‣ ݱࡏ
   ໿ʙ೥ͷखॱॻΛಠΓͰ࡞੒ɻ ʮڀۃͷӡ༻खॱॻʯΛ௥͍ٻΊΔ׆ಈΛ͍ͯ͠·͢ ࣗݾ঺հͱηογϣϯ֓ཁ
4. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ׆ಈ
   ݚڀձ࿦จ 4 ࣗݾ঺հͱηογϣϯ֓ཁ IUUQTXXXOJDBEKQJXQSPHSBNU *OUFSOFU
   8FFL
   
   υΩϡϝϯτηογϣϯ
   4QIJOY
5. • ೔ຊͷ"84ϢʔβίϛϡχςΟͷҰͭɻ
   • ڵຯର৅͸ɺ6OJpFE
   "84
   $-*
   
   • ઃཱ
   
   • "84
   4VNNJU
   
   %BZ
   • ։࠵
   ճ
   ϋϯζΦϯճ υΩϡϝϯτ׆ಈ
   +"846(
   $-*ઐ໳ࢧ෦ ϋϯζΦϯ͋ͨΓͷखॱॻ ࣗݾ঺հͱηογϣϯ֓ཁ • ฏۉ
   ໿ຕ
   • ࠷େ
   ຕ ͜͜Λ͖͔͚ͬʹΫϥ΢υస৬͢Δਓଟ਺
6. Operation Lab ӡ༻ઃܭϥϘ ༨ஊ
   "84
   $-*ެࣜϦϑΝϨϯε 6
7. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ׆ಈ
   ݚڀձ࿦จ 7 ిࢠ௨৴৘ใֶձ ৘ใॲཧֶձ ࣗݾ঺հͱηογϣϯ֓ཁ
8. શͯ4QIJOY͕͋Δ͔ΒͰ͖ͨ • *OUFSOFU
   8FFL
   
   • +"846(
   $-*ઐ໳ࢧ෦
   • ݚڀձ࿦จ Operation Lab ӡ༻ઃܭϥϘ 8
9. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ࡞੒ͷաڈɺݱࡏɺະདྷ 9
10. Operation Lab ӡ༻ઃܭϥϘ ೥൒લʹॻ͍ͨهࣄ 10 https://rsh.csh.sh/misc/20121209-sphinx.html
11. Operation Lab ӡ༻ઃܭϥϘ Ԗච υΩϡϝϯτ࡞੒ͷաڈɺݱࡏ 11 ೖग़ྗͷ෼཭ لݩલ೥ࠒʙ ੈل຤ खॻ͖ ๽ච ໦൛ҹ࡮ ׆൛ҹ࡮ ฏ൘ҹ࡮ λΠϓϥΠλʔ ϫʔϓϩ Ճ޻֓೦ͷ஀ੜ ਵ࣌ग़ྗ
    ࢴ ϓϦϯλʔ ηϚϯςΟοΫ8FC ೪౔൘ɺ໦؆ ೖྗ ग़ྗ ੈلޙ൒ لݩલ೥ࠒʙ ੈلޙ൒ ੈلதࠒ ੈلࠒ ೖग़ྗҰମ ੈل຤ࠒ Ճ޻ͱग़ྗͷࣗಈԽ
    8FC ੈلॳ಄ ೖྗٕज़ ग़ྗٕज़ Ճ޻ٕज़ ݻఆେྔग़ྗ
    ࢴ ·ͩखೖྗ͕લఏ
12. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ࡞੒ͷݱࡏ͔Βະདྷ΁ 12 ηϚϯςΟοΫ8FC Ճ޻ͱग़ྗͷࣗಈԽ
    8FC ੈلॳ಄ ೖྗٕज़ ग़ྗٕज़ Ճ޻ٕज़ ͕͜͜ະͩ
    खॻ͖ɾखೖྗ ೖྗ ग़ྗ ʮυΩϡϝϯτͷશͯΛਓ͕ॻ͘ʯͱ͍͏؍೦͔Βͷ୤٫͕ඞཁ ਓͷखͰશͯॻ͜͏ͱ͢Δ͔Β ʮυΩϡϝϯτݏ͍ʯʹͳΔ
13. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ࡞੒ͷະདྷ
    XJUI
    4QIJOY 13 ೖྗٕज़ ग़ྗٕज़ Ճ޻ٕज़ ೖྗ ग़ྗ reSTructured Text Parser Builder Theme reSTructured Text ਓ͕ॻ͘ ػց͕ॻ͘ Ϛγϯ • υΩϡϝϯτͷ͏ͪɺਓ͕ॻ͘෦෼ͱɺػցʹॻ͔ͤΔ෦෼Λҙࣝతʹ෼཭͢Δɻ
    • ػցʹॻ͔ͤΔυΩϡϝϯτΛ໌֬ʹ͢Δ
    • $47΍:".-ͳͲͷՄಡੑͷߴ͍ߏ଄Խσʔλ
    • ݴޠͷώΞυΩϡϝϯτػೳͰੜ੒Ͱ͖Δσʔλ
    • ੲ͸ɺ9.-΋༗ޮͩͬͨ
    • ػցʹॻ͔ͤͨυΩϡϝϯτύʔπΛɺਓ͕ॻ͍ͨυΩϡϝϯτ͔ΒΠϯΫϧʔυ͢Δɻ
14. Operation Lab ӡ༻ઃܭϥϘ ͱ͋ΔKVTษڧձ
    ೥݄ 14 TTNKQ
    ૑ઃऀ ӡ༻υΩϡϝϯτॻ͘ͷΩϥΠ )BUBOP ΄͍ͬ ӡ༻υΩϡϝϯτॻ͘ͷ௒ָ͍͠XXXX
15. Operation Lab ӡ༻ઃܭϥϘ ͜Ε͸িܸͷCFGPSFBGUFSͩͬͨ 15 TTNKQ
    ૑ઃऀ ӡ༻υΩϡϝϯτॻ͘ͷ
    ΩϥΠ ӡ༻υΩϡϝϯτॻ͘ͷ
    ௒ָ͍͠XXXX
16. Operation Lab ӡ༻ઃܭϥϘ ݸਓతʹ΋ 16 ӡ༻υΩϡϝϯτॻ͘ͷ
    ௒ָ͍͠XXXX )BUBOP υΩϡϝϯτͷΞ΢τϓοτޮ཰͸ഒऑʹ ೥ҎલͱҎ߱ͷൺֱ ೥ؒϖʔδऑ
    WT
    ೥ϖʔδऑ
17. Operation Lab ӡ༻ઃܭϥϘ ʮυΩϡϝϯτͷશͯΛਓ͕ॻ͘ʯ
    ͱ͍͏؍೦͔Βͷ୤٫ 17
18. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ࡞੒ΛਓͱػցͰ෼୲͢Δ 18 • υΩϡϝϯτͷ͏ͪɺਓ͕ॻ͘෦෼ͱɺػցʹॻ͔ͤΔ෦෼Λҙࣝతʹ෼཭͢Δɻ
    • ػցʹॻ͔ͤΔυΩϡϝϯτΛ໌֬ʹ͢Δ
    • $47΍:".-ͳͲͷՄಡੑͷߴ͍ߏ଄Խσʔλ
    • ݴޠͷώΞυΩϡϝϯτػೳͰੜ੒Ͱ͖Δσʔλ
    • ੲ͸ɺ9.-΋༗ޮͩͬͨ
    • ػցʹॻ͔ͤͨυΩϡϝϯτύʔπΛɺਓ͕ॻ͍ͨυΩϡϝϯτ͔ΒΠϯΫϧʔυ͢Δɻ 4QIJOYͷΠϯΫϧʔυػೳ͕ڧྗ 4QIJOYͷஔ׵ػೳ͕ڧྗ ೖྗٕज़ ग़ྗٕज़ Ճ޻ٕज़ ೖྗ ग़ྗ reSTructured Text reSTructured Text ਓ͕ॻ͘ ػց͕ॻ͘ Ϛγϯ
19. Operation Lab ӡ༻ઃܭϥϘ ͲͷΑ͏ʹਓͱػցͰ෼୲͢Δ͔ 19 ਓ͕ॻ͘ ػց͕ॻ͘ Ϛγϯ ਓʹ͔͠ॻ͚ͳ͍෦෼Λॻ͘ ਓ͕ॻ͔ͳͯ͘΋ྑ͍ͱ͜ΖΛ ॻ͘ ʮػց͕ॻ͚Δͱ͜ΖΛॻ͘ʯͩͱ͍ͭ·Ͱܦͬͯ΋
    ਓ͕ॻ͘υΩϡϝϯτ͸ݮΒͳ͍
    গ͠ແཧͯ͠΋ػցʹॻ͔ͤΔ
20. Operation Lab ӡ༻ઃܭϥϘ ʮػցʹυΩϡϝϯτΛॻ͔ͤΔʯ 20
21. ػցʹॻ͔ͤΔ
    ࣗ෼ͷ৔߹ • ώΞυΩϡϝϯτ
    • DBUίϚϯυ
    • TFEίϚϯυ
    • ඪ४ग़ྗΛϑΝΠϧʹϦμΠϨΫτ Operation Lab ӡ༻ઃܭϥϘ 21 γΣϧͷجຊػೳͰे෼ʹՄೳ
22. 4QIJOYͷॏཁͳػೳ • ΠϯΫϧʔυػೳ
    • JODMVEF
    SF45ϑΝΠϧΛΠϯΫϧʔυ͢Δ
    • MJUFSBMJODMVEF
    ιʔείʔυΛΠϯΫϧʔυ͢Δ
    • DTWUBCMF
    DTWϑΝΠϧΛΠϯΫϧʔυ͢Δ
    • ஔ׵ػೳ
    • ςϯϓϨʔτͷಛఆͷ৔ॴΛॻ͖׵͑ͯग़ྗͰ͖Δ
    • UPDUSFF
    • จॻߏ଄ΛܾΊΔ Operation Lab ӡ༻ઃܭϥϘ 22
23. Operation Lab ӡ༻ઃܭϥϘ ʮͲ͏ߏ଄Խ͢Δ͔ʯΛৗʹߟ͑Δ 23
24. ʮͲ͏ߏ଄Խ͢Δ͔ʯΛৗʹߟ͑Δ͜ͱ͕େࣄ Operation Lab ӡ༻ઃܭϥϘ 24 https://rsh.csh.sh/misc/20121209-sphinx.html ߏ଄ԽΛ͢Ε͹ɺͦͷ޻਺ʹݟ߹ͬͨ੒Ռ͕ಘΒΕΔ ਓͱػցͰυΩϡϝϯτ࡞੒ͷ෼୲͕Ͱ͖Δ ͦ͏ɺ4QIJOYͳΒ͹ɺͶ
25. ʮͲ͏ߏ଄Խ͢Δ͔ʯΛৗʹߟ͑Δ͜ͱ͕େࣄ Operation Lab ӡ༻ઃܭϥϘ 25 4QIJOYͰυΩϡϝϯτΛॻ͍͍ͯΔͱ ಄ͷத͕ͲΜͲΜߏ଄Խ͞Ε͍ͯ͘ ग़ྗ͕ඒ͘͠ͳ͍৔߹͸ɺߏ଄͕͓͔͍͠
26. Operation Lab ӡ༻ઃܭϥϘ σϞ 26
27. Operation Lab ӡ༻ઃܭϥϘ ·ͱΊ 27
28. ·ͱΊ
    େྔʹυΩϡϝϯτΛखܰʹ࡞Δ • ਓͱػցͰ෼୲͢Δ
    • γΣϧίϚϯυͰ΋े෼ʹڧྗ
    • ʮͲ͏ߏ଄Խ͢Δ͔ʯΛৗʹߟ͑Δ͜ͱ͕େࣄ Operation Lab ӡ༻ઃܭϥϘ 28
29. Operation Lab ӡ༻ઃܭϥϘ 29 খٶ͞Μɺਗ਼ਫ઒͞Μ
    ͓ੈ࿩ʹͳ͍ͬͯ·͢
30. Operation Lab ӡ༻ઃܭϥϘ એ఻ 30
31. • 3
    &$جૅ &#4
    
    • 3
    &$جૅ ".*
    
    • 3
    *".ೖ໳
    
    • 3
    *".جૅ *".ϙϦγʔ
    
    • 3
    *".جૅ *".ϩʔϧ
    
    • 3
    *".جૅ ΠϯελϯεϓϩϑΝΠϧ
    ্݄० એ఻
    +"846(
    $-*ઐ໳ࢧ෦
    ΦϯϥΠϯ ࣗݾ঺հͱηογϣϯ֓ཁ खॱॻ͸શͯ4QIJOYͰ࡞੒
32. Operation Lab ӡ༻ઃܭϥϘ ࢀߟ
    աڈͷൃදࢿྉ 32 IUUQTXXXPQTMBCKQQVCMJTI աڈͷൃදࢿྉ͸
    0QT-BCKQ
    ͱ͍͏αΠτʹஔ͍ͯ͋Γ·͢ɻ
33. Operation Lab ӡ༻ઃܭϥϘ 33 IUUQXXXPQFSBUJPOMBCDPKQ OperationLab ӡ༻ઃܭ