なぜSphinxで手順書を作るのか /20180425-sphinx-documentation

ssmjp 201804での発表資料です。

詳細: https://www.opslab.jp/publish/20180425-ssmjp-sphinx.html

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

Transcript

1. Operation Lab ӡ༻ઃܭϥϘ 1 ӡ༻ઃܭϥϘ߹ಉձࣾ
   
   
   γχΞΞʔΩςΫτ
   ೾ా໺
   ༟Ұ  ͳͥ4QIJOYͰखॱॻΛ࡞Δͷ͔ TTNKQ
   
2. Operation Lab ӡ༻ઃܭϥϘ 2 (6*࡞ۀ͔Β
   ଔۀ͠Α͏ ʮӡ༻ࣗಈԽʯ͢Δલʹ લճͷ͓୊
3. Operation Lab ӡ༻ઃܭϥϘ 3
4. Operation Lab ӡ༻ઃܭϥϘ ӡ༻ࣗಈԽΛߟ͑Δલʹ୤(6*Λ • ࡞ۀ୯Ґͷ੾Γग़͠ํ͕͹Β͖ͭ΍͍͢ɻ
   • ΦϒδΣΫτࢦ޲ϓϩάϥϛϯάͷجૅΛ஌Βͳ͍ͱ
   
   มͳίʔυʹͳΔɻ อकͰ͖ͳ͘ͳΔ
   • 6*վగͰಈ͔ͳ͘ͳΔ࣮૷ɺ௥͍෇͔ͳ͍ίʔυमਖ਼ɻ ͦ΋ͦ΋(6*࡞ۀͷ
   ίʔυԽ͸ൺֱత೉͍͠
5. Operation Lab ӡ༻ઃܭϥϘ ίϚϯυ΍"1*ͳͲ௿ϨϕϧͰػೳΛཧղͯ͠࡞ۀ ӡ༻ࣗಈԽΛߟ͑Δલʹ ͳΜͱͳ͘ཧղ͍ͯ͠Ε͹ɺ͕ͭͭͳ͘࡞ۀ׬ྃ (6* $-* 6*վగͰࠞཚ͢Δݱ৔ɺ௥͍෇͔ͳ͍खॱॻվగ 6*վగͷӨڹͳ͠ɺ"1*վగͰ΋৽ػೳΛਖ਼֬ʹ೺Ѳ ௕ظతͳֶशޮՌʹେ͖ͳࠩ ҰาҰา࣮֬ʹ஌ݟ͕ੵΈ্͕͍ͬͯ͘ ·ͣ୤ʮ(6*࡞ۀʯΛਐΊΑ͏
6. ʮӡ༻ࣗಈԽʯͷܦݧଇ 6 ੒ޭͨࣗ͠ಈԽ • ࣗಈԽͷޮՌʹ͍ͭͯɺCFGPSFBGUFS͕໌֬ͳ΋ͷ
   • ܧଓతʹϝϯςφϯεͰ͖ΔΑ͏ʹૄ݁߹ʹ࡞੒ͨ͠΋ͷ
   • ໨తΛ໌֬ʹ͠ɺτοϓμ΢ϯࣜʹ࡞੒ͨ͠΋ͷɻ
   • खॱॻʹԊͬͯ࡞੒ͨ͠΋ͷ • खۙͳͱ͜Ζ͔ΒϘτϜΞοϓࣜʹ࡞੒ͨ͠΋ͷɻ
   • ʮࣗಈԽʯΛ໨తʹͨ͠΋ͷɻ ਅͷ໨త͕໎૸ͨ͠
   • ʮເͷπʔϧʯΛ໨ࢦͨ͠΋ͷɻ ࣦഊͨࣗ͠ಈԽ ৘ใॲཧֶձ
   υΩϡϝϯτίϛϡχέʔγϣϯݚڀ
   ୈճݚڀձ
   ൃදࢿྉ͔Β Operation Lab ӡ༻ઃܭϥϘ
7. Operation Lab ӡ༻ઃܭϥϘ • खॱॻϕʔεͷࣗಈԽ͸ଞਓͰ΋ཧղ͠΍͍͢
   • ࡞ۀखॱΛྲྀΕ࡞ۀԽ͠ɺద੾ʹ੔ཧɾ෼ׂ͢Δ͜ͱͰΘ͔Γ΍͘͢ͳΔɻ
   • खॱॻϕʔεͷࣗಈԽ͸ϞϊϦγοΫԽΛආ͚΍͍͢
   • ͭͷ͜ͱΛ্खʹͰ͖ΔখཻͷखॱॻΛ࡞੒͠ɺखॱ ࢓༷ ʹैͬͯࣗಈॲཧΛ࣮૷ ͢Δ͜ͱͰɺϞϊϦγοΫ େ͖ͳҰմ ԽΛආ͚Δ͜ͱ͕༰қͰ͋Δɻ
   • खॱॻϕʔεͷࣗಈԽ͸8FC"1*ͱ૬ੑ͕ྑ͍
   • ैདྷ͸ॲཧσʔλΛϝϞϦ౉͢͠Δ͜ͱ͕ओྲྀͰɺϑΝΠϧ౉͠͸ʮ֨޷ѱ͍ʯͱ͞ Ε͖ͯͨɻ
   • 8FC"1*΁ͷ৘ใ఻ୡ͸ϑΝΠϧ౉͠ 1045 ʹͳΔͨΊɺΉ͠ΖϑΝΠϧ౉͠ͷํ͕ ॊೈʹ8FC"1*࿈ܞͰ͖ΔΑ͏ʹͳ͖ͬͯͨɻ
   • ࡞ۀؒʹ͓͚Δσʔλड͚౉͠ΛϑΝΠϧ౉͢͠Δ͜ͱͰɺ8FC"1*࿈ܞʹΑΔࣗಈ ԽΛࢹ໺ʹೖΕͨखॱΛ࣮ݱ͢Δ͜ͱ͕Ͱ͖Δɻ ৘ใॲཧֶձ
   υΩϡϝϯτίϛϡχέʔγϣϯݚڀ
   ୈճݚڀձ
   ൃදࢿྉ͔Β खॱΛߏ଄Խ͔ͯ͠ΒࣗಈԽ͢Δ
8. Operation Lab ӡ༻ઃܭϥϘ खॱΛ$-*Խ͔ͯ͠ΒࣗಈԽ͢Δ • $-*ϕʔεͷࣗಈԽ͸ଞਓͰ΋ཧղ͠΍͍͢
   • ࡞ۀखॱΛྲྀΕ࡞ۀԽ͠ɺద੾ʹ੔ཧɾ෼ׂ͢Δ͜ͱͰΘ͔Γ΍͘͢ͳΔɻ
   • $-*ϕʔεͷࣗಈԽ͸ϞϊϦγοΫԽΛආ͚΍͍͢
   • ͭͷ͜ͱΛ্खʹͰ͖ΔখཻͷεΫϦϓτΛ࡞੒͠ɺखॱ ࢓༷ ʹैͬͯϑϩʔॲཧ Λ࣮૷͢Δ͜ͱͰɺϞϊϦγοΫ େ͖ͳҰմ ԽΛආ͚Δ͜ͱ͕༰қͰ͋Δɻ
   • $-*ϕʔεͷࣗಈԽ͸8FC"1*ͱ૬ੑ͕ྑ͍
   • ैདྷ͸ॲཧσʔλΛϝϞϦ౉͢͠Δ͜ͱ͕ओྲྀͰɺϑΝΠϧ౉͠͸ʮ֨޷ѱ͍ʯͱ͞ Ε͖ͯͨɻ
   • 8FC"1*΁ͷ৘ใ఻ୡ͸ϑΝΠϧ౉͠ 1045 ʹͳΔͨΊɺΉ͠ΖϑΝΠϧ౉͠ͷํ ͕ॊೈʹ8FC"1*࿈ܞͰ͖ΔΑ͏ʹͳ͖ͬͯͨɻ
   • ࡞ۀؒʹ͓͚Δσʔλड͚౉͠ΛϑΝΠϧ౉͢͠Δ͜ͱͰɺ8FC"1*࿈ܞʹΑΔࣗಈ ԽΛࢹ໺ʹೖΕͨखॱΛ࣮ݱ͢Δ͜ͱ͕Ͱ͖Δɻ
9. Operation Lab ӡ༻ઃܭϥϘ 4QIJOYͰ͸͡ΊΔखॱॻۦಈӡ༻
10. Operation Lab ӡ༻ઃܭϥϘ 4QIJOYલ࢙ 10 ಄͔Β͓৲·Ͱ ਓ͕खͰॻ͘͜ͱ Λ૝ఆ͍ͯ͠·ͤΜ͔? खॱॻΛॻ͕࣌ؒ͘
11. Operation Lab ӡ༻ઃܭϥϘ 4QIJOYલ࢙ 11 खॱΛXMLͰखॻ͖ XSLTͰύʔεͯ͠HTMLԽ ͦΜͳ࣌୅͕
    ࣗ෼ʹ΋͋Γ·ͨ͠
12. Operation Lab ӡ༻ઃܭϥϘ 4QIJOYલ࢙ 12 91BUIͭΒ͍ खॱΛXMLͰखॻ͖ XSLTͰύʔεͯ͠HTMLԽ
13. Operation Lab ӡ༻ઃܭϥϘ ͳͥɺ9.-ʹ͔ͨ͠
    ೥ࠒ 13 Doc ΠϯΫϧʔυ ΠϯΫϧʔυΛલఏͱ͢Δ࣌୅΁ ࠶ར༻Λલఏ ݸผࣄ৘Λهड़ when where who what how υΩϡϝϯτࢿ࢈Λ࠶ར༻͢Δ why ਓ͕ຖճهड़͢Δ ౰࣌͸ϚογϡΞοϓͷᴈ໌ظ
14. Operation Lab ӡ༻ઃܭϥϘ ͳͥΠϯΫϧʔυ 14 Doc ΠϯΫϧʔυ खॻ͖Λલఏͱ͠ͳ͍࣌୅΁ ࠶ར༻Λલఏ ݸผࣄ৘Λهड़ when where who what how υΩϡϝϯτࢿ࢈Λ࠶ར༻͢Δ why ਓ͕ຖճهड़͢Δ γΣϧεΫϦϓτͰ (൒)ࣗಈੜ੒
15. Operation Lab ӡ༻ઃܭϥϘ ٹੈओͷొ৔
     15 γΣϧεΫϦϓτͰੜ੒ͨ͠खॱॻΛ SphinxͰΠϯΫϧʔυͯ͠HTMLԽ Ͱ͖Δ
16. ΠϯΫϧʔυΛ׆༻͢ΔυΩϡϝϯςʔγϣϯ • $47σʔλΛΠϯΫϧʔυͯ͠ςʔϒϧදࣔ
    • ιʔείʔυΛΠϯΫϧʔυͯ͠ϋΠϥΠτදࣔ
    • ιʔείʔυͷಛఆൣғΛΠϯΫϧʔυͯ͠දࣔ
    • ஔ׵ͷఆٛͱద༻৔ॴͷهड़ΛΠϯΫϧʔυ
    • υΩϡϝϯτͷύʔπΛΠϯΫϧʔυ
    SF45SVDUVSFE
    5FYUܗࣜ Operation Lab ӡ༻ઃܭϥϘ Ұ౓ॻ͍ͨυΩϡϝϯτͷ࠶ར༻΍γεςϜͷग़ྗ
    Λ׆͔ͨ͠൒ࣗಈυΩϡϝϯςʔγϣϯ ଟ࠼ͳΠϯΫϧʔυػೳ
17. Operation Lab ӡ༻ઃܭϥϘ ࣄྫ
18. ΠϯΫϧʔυΛ׆༻͢ΔυΩϡϝϯςʔγϣϯ Operation Lab ӡ༻ઃܭϥϘ υΩϡϝϯτͷύʔπΛΠϯΫϧʔυ
    
    SF45SVDUVSFE
    5FYUܗࣜ खॱॻ 4QIJOY खॱύʔπ ΠϯΫϧʔυ खॱύʔπ ΠϯΫϧʔυ
19. ΠϯΫϧʔυΛ׆༻͢ΔυΩϡϝϯςʔγϣϯ Operation Lab ӡ༻ઃܭϥϘ ஔ׵ͷఆٛͱద༻৔ॴͷهड़ΛΠϯΫϧʔυ खॱॻ 4QIJOY ஔ׵ςʔϒϧ ஔ׵จࣈྻ ΠϯΫϧʔυ ஔ׵ςʔϒϧͷهड़ʹैͬͯ
    खॱॻͷ֘౰෦෼͕ॻ͖ସΘΔɻ
20. ΠϯΫϧʔυΛ׆༻͢ΔυΩϡϝϯςʔγϣϯ Operation Lab ӡ༻ઃܭϥϘ $47σʔλΛΠϯΫϧʔυͯ͠ςʔϒϧදࣔ $47ϑΝΠϧ 4QIJOY DTWUBCMF
    σΟϨΫςΟϒ εΫϦϓτ ࣗಈੜ੒ ςʔϒϧදࣔ
21. ΠϯΫϧʔυΛ׆༻͢ΔυΩϡϝϯςʔγϣϯ Operation Lab ӡ༻ઃܭϥϘ ιʔείʔυΛΠϯΫϧʔυͯ͠ϋΠϥΠτදࣔ ૢ࡞ର৅ 4QIJOY MJUFSBMJODMVEF
    σΟϨΫςΟϒ γΣϧ
    εΫϦϓτ ࣗಈ࣮ߦՄೳ ίϚϯυखॱ खಈ࣮ߦՄೳ
22. Operation Lab ӡ༻ઃܭϥϘ ࣄྫ
    +"846(
    $-*ઐ໳ࢧ෦ 22 ENV FLOW RESULT API ίϚϯυ γφϦΦ ϋϯζΦϯखॱ γΣϧεΫϦϓτͰੜ੒ + ΧελϜ ਓ͕هड़ ΠϯΫϧʔυ ࡞Γஔ͖ͨ͠େྔͷυΩϡϝϯτϞδϡʔϧΛ ΠϯΫϧʔυͯ͠ɺ৽نυΩϡϝϯτΛ࡞੒ ཁૉਤ
    ճ։࠵த໿ճ෼ 4QIJOYͷ׆༻ྫ ࢖͍ࣺͯखॱ
23. Operation Lab ӡ༻ઃܭϥϘ ࠷ۙ
    +"846(
    $-*ઐ໳ࢧ෦ 23 γΣϧεΫϦϓτͰ શ໘తʹࣗಈੜ੒Խ Doc ΠϯΫϧʔυ ࠶ར༻Λલఏ ݸผࣄ৘Λهड़ when where who what how υΩϡϝϯτࢿ࢈Λ࠶ར༻͢Δ why ਓ͕ຖճهड़͢Δ
24. Operation Lab ӡ༻ઃܭϥϘ 24 ࿦ཧతͳໃ६΍ෆ੔߹ΛഉআͰ͖Δ ࣄલ৚݅ɺࣄޙ৚݅ͷଥ౰ੑ ࣗಈੜ੒ʹඞཁͳཁૉ खॱॻࣗಈੜ੒ԽͷϝϦοτ ࿦ཧతͳਖ਼͠͞ (໨తద߹ੑ) ࿦ཧతͳ੔߹ੑ ໋໊نଇ΍໊લۭؒͷنଇԽ͕ਐΉ
    
    ߋʹࣗಈԽ͠΍͘͢ͳΔ
25. Operation Lab ӡ༻ઃܭϥϘ -FU`T
    CVZ
26. Operation Lab ӡ༻ઃܭϥϘ ·ͱΊ
27. Operation Lab ӡ༻ઃܭϥϘ ·ͱΊ
    खॱॻͷ࡞Γํ 27 when where who what how υΩϡϝϯτࢿ࢈Λ࠶ར༻͢Δ why ਓ͕ຖճهड़͢Δ Doc ΠϯΫϧʔυ ΠϯΫϧʔυΛલఏͱ͢Δ࣌୅΁ ࠶ར༻Λલఏ ݸผࣄ৘Λهड़ Ұ౓ॻ͍ͨυΩϡϝϯτͷ࠶ར༻΍γεςϜͷग़ྗ
    Λ׆͔ͨ͠൒ࣗಈυΩϡϝϯςʔγϣϯ
28. Operation Lab ӡ༻ઃܭϥϘ 28 ΠϯΫϧʔυΛલఏͱ͢Δ࣌୅΁ MarkdownܗࣜΛຖճखͰॻ͖·͔͢? SphinxͰυΩϡϝϯτࢿ࢈Λ ΠϯΫϧʔυ͠·͔͢? υΩϡϝϯτͷ࠶ར༻͕લఏ ·ͱΊ
    खॱॻͷ࡞Γํ
29. Operation Lab ӡ༻ઃܭϥϘ େࣄͳ͜ͱ͸ʮۀ຿ͷߏ଄Խʯ ʮ໰୊ΛࠜੑͰղܾ͢Δͷ͸അࣛͰ͢ɻ
    ໰୊ΛΤϯδχΞϦϯάͰղܾ͢Δͷ͕ ΤϯδχΞͷ࢓ࣄͰ͢ʯ
    !ZPTIJPSJ ߏ଄Խ ͜͜Ͱ͸ʮΤϯδχΞϦϯά ޻ֶ ͷ࣮ફʯʹ͍ۙҙຯͰ࢖͍·͢ɻ
    ޻ֶͰ͸ԿΒ͔ͷߏ଄෺ɾߏ଄ମΛ࡞Δ͜ͱ͕ෆՄආͳͨΊͰ͢ɻ http://d.hatena.ne.jp/Yoshiori/20120217/1329491437
30. Operation Lab ӡ༻ઃܭϥϘ 30 ʮӡ༻ࣗಈԽʯΑΓ΋ ʮӡ༻ߏ଄Խʯͷະདྷ΁ ·ͣ͸ͪΌΜͱͨ͠ ߏ଄తͳ खॱॻΛॻ͜͏ ࣗಈԽ͸ͦͷઌͷ࿩ͩ
31. Operation Lab ӡ༻ઃܭϥϘ 31 IUUQXXXPQFSBUJPOMBCDPKQ OperationLab ӡ༻ઃܭ