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

Ea29e2b19d11b48f867ae71d6a6de5df?s=47 opelab
June 10, 2020

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

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

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

Ea29e2b19d11b48f867ae71d6a6de5df?s=128

opelab

June 10, 2020
Tweet

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 *OUFSOFU8FFLυΩϡϝϯτηογϣϯ 4QIJOY

  5. • ೔ຊͷ"84ϢʔβίϛϡχςΟͷҰͭɻ • ڵຯର৅͸ɺ6OJpFE"84$-* • ઃཱ • "844VNNJU%BZ • ։࠵ճ

    ϋϯζΦϯճ υΩϡϝϯτ׆ಈ+"846($-*ઐ໳ࢧ෦ ϋϯζΦϯ͋ͨΓͷखॱॻ ࣗݾ঺հͱηογϣϯ֓ཁ • ฏۉ໿ຕ • ࠷େຕ ͜͜Λ͖͔͚ͬʹΫϥ΢υస৬͢Δਓଟ਺
  6. Operation Lab ӡ༻ઃܭϥϘ ༨ஊ"84$-*ެࣜϦϑΝϨϯε 6

  7. Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτ׆ಈݚڀձ࿦จ 7 ిࢠ௨৴৘ใֶձ ৘ใॲཧֶձ ࣗݾ঺հͱηογϣϯ֓ཁ

  8. શͯ4QIJOY͕͋Δ͔ΒͰ͖ͨ • *OUFSOFU8FFL • +"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 ӡ༻ઃܭϥϘ υΩϡϝϯτ࡞੒ͷະདྷXJUI4QIJOY 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 ӡ༻ઃܭ