Writing documentation can be fun with plugin system

https://fortee.jp/burikaigi-2025/proposal/03ac7594-fce1-4dad-9dd0-c37649127f90

Transcript

1. ָ͍͠υΩϡϝϯςʔγϣϯ Λ໨ࢦͯ͠ —RDoc֦ுػೳج൫ BuriKaigi 2025 OKURA Masafumi, 2025-02-01
2. ͸͡Ίʹɿ͜ͷൃදʹ͓͚Δ༻ޠͷఆٛ • υΩϡϝϯτɿιʔείʔυʹίϝϯτͱͯ͠෇ਵ͢ΔλΠϓͷจ ॻɺREADMEͳͲ͸ݪଇతʹআ֎ • υΩϡϝϯςʔγϣϯɿυΩϡϝϯτͷू߹ʢݩʑͷҙຯʣɺ͋Δ͍ ͸υΩϡϝϯτΛهड़͢Δ͜ͱʢಠࣗͷҙຯʣ • υΩϡϝϯςʔγϣϯπʔϧɿهड़͞ΕͨυΩϡϝϯτΛਓؒʹΑͬ ͯར༻Մೳͳܗʹม׵͢Δπʔϧ • RDocɿRubyʹඪ४ఴ෇͞Ε͍ͯΔυΩϡϝϯςʔγϣϯπʔϧ
3. υΩϡϝϯτΛ ॻ͘ͷ͸ָ͍͠ Ͱ͔͢ʁ
4. ࢲ͸͋·Γ ָ͋͘͠Γ·ͤΜ :)
5. WHY?
6. ͳͥυΩϡϝϯτΛॻ͘ͷ͸ָ͘͠ͳ͍ͷ͔ • ίʔυΛॻ͘΄͏ָ͕͍͔͠Β • Θ͔Δ • ͨ͘͞Μॻ͔ͳͯ͘͸͍͚ͳ͍͔Β • ͳΜͱ͔Ͱ͖ΔͷͰ͸ʁ • ॻ͍ͨυΩϡϝϯτ͕໾ʹཱͭؾ͕͠ͳ͍͔Β • ໾ʹཱͭΑ͏ͳυΩϡϝϯτΛੜ੒Ͱ͖ͨΒʁ
7. ͨͷ͍͠υΩϡϝϯ ςʔγϣϯͷͨΊʹɺ υΩϡϝϯςʔγϣϯ πʔϧ͕Ͱ͖Δ͜ͱ
8. 1. লྗԽ
9. 2. ༗༻Խ
10. ͋ͳͨ͸୭ʁ
11. ࣗݾ঺հ • ໊લɿେ૔խ࢙ʢ͓͓͘Β·͞;Έʣ • ॴଐɿϑϦʔϥϯε • ՝֎׆ಈɿKaigi on RailsɺTokyoWomen.rbɺRubygemsίʔυϦʔ σΟϯά෦ʢҎ্ओ࠵ʣɺOSS׆ಈʢGitHub Star ߹ܭ1000௒ʣ • ࢲͱBuriKaigiɿ2020೥ొஃʢinstance_evalʣɺ2022೥ొஃ ʢDSLʣɺ2024೥ొஃʢRubyʹBoolean͕ͳ͍ཧ༝ʣ
15. ָ͍͠υΩϡϝϯςʔγϣϯ Λ໨ࢦͯ͠—RDoc֦ுػೳج ൫ BuriKaigi 2025 OKURA Masafumi, 2025-02-01
16. Rubyist
17. Ruby
18. RDoc
19. RDocͱ͸ • Rubyʹඪ४ఴ෇͞Ε͍ͯΔʢผ్ͷΠϯετʔϧ͕ෆཁͳʣυΩϡϝϯςʔ γϣϯπʔϧ • HTMLυΩϡϝϯτΛੜ੒͢Δ`rdoc`ίϚϯυͱίϚϯυϥΠϯ͔ΒυΩϡϝ ϯτΛӾཡ͢Δ`ri`πʔϧΛಉࠝ • RDoc͕σϑΥϧτͰѻ͏ϑΥʔϚοτ͸`RDϑΥʔϚοτ`ͱݴ͏͕ɺRDoc ϑΥʔϚοτͱݺ͹ΕΔ͜ͱ΋͋Δ • Ruby on RailsͰ࠾༻͞Ε͍ͯΔଞɺRubyຊମ΋͜ͷه๏
21. ΍΍͍͜͠࿩
22. YARD
23. YARDͱ͸ • Rubyͷඇඪ४υΩϡϝϯςʔγϣϯπʔϧ • ϥΠϒϥϦʹ͓͚ΔγΣΞ͸ѹ౗తʹߴ͍ • ಠࣗͷʢ@returnͷΑ͏ͳʣه๏Λ࣋ͭ • ͪͳΈʹ໊শ͸”Yay! A Ruby Documentation”ͷ಄ࣈޠ
25. υΩϡϝϯςʔγϣϯ πʔϧ ʢͱϑΥʔϚοτʣ ͕2ͭ͋Δʂ
26. RubyͷੈքͰ υΩϡϝϯςʔγϣϯ πʔϧ͕΍Δ΂͖͜ͱ
27. 0. πʔϧͷ ౷߹
28. ͓඼ॻ͖ • πʔϧͷ౷߹ • υΩϡϝϯςʔγϣϯͷলྗԽ • υΩϡϝϯςʔγϣϯͷ༗༻Խ
29. ௨૗௿Իͱͯ͠ͷ ֦ுػೳج൫
30. 0. πʔϧͷ ౷߹
31. RDoc or YARD
32. RDoc or YARD
33. ͳͥRDocͳͷ͔ • ඪ४ఴ෇͞Ε͍ͯΔͷͰผ్ͷΠϯετʔϧͳͲ͕ෆཁ • RDoc͸ͳ͘ͳΔ͜ͱ͸ͳ͍ • CRubyͷιʔείʔυ಺ͷυΩϡϝϯτΛղऍͰ͖Δͷ͸RDocͷΈ • YARDͷϝϯςφϯεঢ়گ͕ෆ҆ • େ͖Ίͷվળ΋࠷ۙ͸গͳ͍͠ɺϝϯςφϯε͸جຊݸਓ͕͍ͯ͠ Δ
34. Ͳ͏౷߹͢Δʁ
35. ֦ுػೳج൫Ͱ ΍Γ͍ͨʂ
36. ͳ֦ͥுػೳج൫ͳͷ͔ • YARDؔ܎ͷػೳ͸ৗʹ࢖͏ͱ͸ݶΒͳ͍ • ֦ுػೳʹͯ͠औΓ֎͠Մೳʹ͢Δ • ຊମʹ͍ۙͱ͜ΖʹೖΕΔͱϝϯςφϯεΛࠔ೉ʹ͢ΔՄೳੑ͕͋Δ • YARDຊମͷίʔυΛ࢖͍ͨ͘ͳ͍ͷͰίʔυ͸1͔Βॻ͘ • ํ਑ΛܾΊΔࣗ༝͕͋Δ
37. ֦ுػೳج൫ͷઃܭ • RDocͷطଘίʔυ಺͔ΒΠϕϯτΛൃՐͤ͞Δʢྫɿpost_parseʣ • ֤֦ுػೳ͸ΠϕϯτΛϦοεϯ͠ɺ؀ڥΦϒδΣΫτΛड͚औΓɺ มߋ͢Δ • ؀ڥΦϒδΣΫτ͸RDocຊମͷ৘ใ΍֤֦ுػೳ͔Βड͚औͬͨ σʔλΛอ࣋͢Δ • RDocͷطଘίʔυͰ೚ҙͷλΠϛϯάͰݱࡏͷ؀ڥΛࢀর͢Δ
38. ֦ுػೳج൫ͰYARDΛRDocʹ౷߹͢Δ • ·ͣYARDύʔαʔΛ࡞Δ • खॻ͖ͱύʔαʔδΣωϨʔλʔͷ2ͭͷखஈ͕͋Δ͕ɺ͓ͦΒ͘खॻ͖ͷํָ͕ • ίϝϯτจࣈྻͷऔಘ͕ऴΘͬͨλΠϛϯάͰΠϕϯτΛൃՐ͢Δ • YARD֦ுػೳ͕ΠϕϯτΛϦοεϯ͠ɺ؀ڥΦϒδΣΫτ͔ΒίϝϯτจࣈྻΛऔ ಘ͢Δ • YARDύʔαʔͰίϝϯτจࣈྻΛύʔε͠ɺܕ৘ใͳͲΛऔಘͯ͠؀ڥΦϒδΣΫ τʹอଘ͢Δ
39. 1. লྗԽ
40. υΩϡϝϯτΛ ॻ͘ͷ͸ ΊΜͲ͍͘͞…
41. υΩϡϝϯτͷΊΜͲ͍͘͞ɺ͋Δ͋Δ • `@example`తͳίʔυྫ͕௕͘ͳͬͯεΫϩʔϧ͠ͳ͍ͱ࣍ͷϝιο υʹͨͲΓண͚ͳ͍ • ϝιουͷ࢓༷͕ॻ͍ͯ͋Δ͚Ͳɺࡉ͔͍ͱ͜ΖΛ஌ΔͨΊʹ݁ہ࣮ ૷ͱςετίʔυΛಡΉ • ʲRubyݶఆʳҾ਺΍ฦΓ஋ͷܕΛυΩϡϝϯςʔγϣϯπʔϧݻ༗ ͷϑΥʔϚοτͰॻ͚͘ͲɺͦΕͱ͸ผʹܕπʔϧͷܕ΋͋Δ
42. ໰୊1ɿ example͕௕͍
43. ղܾࡦ1ɿ example͸ ผϑΝΠϧʹ͢Δ
44. example͸ผͷϑΝΠϧʹ͢Δ • ϥΠϒϥϦͩͱ`examples`σΟϨΫτϦ͕͋Δ͜ͱ΋ଟ͍ͷͰɺͦ͜ ʹʮͲͷΫϥε΍ϝιουʹඥ෇͔͘ʯͷλά͕෇͚͹͍͚Δ͔΋ • ϓϩμΫτͩͱɺςετίʔυ͕࣮ࡍͷར༻ྫʹ͍ۙ৔߹͕ଟ͍ͷ ͰɺςετίʔυΛexampleͱͯ͠ར༻Ͱ͖ͳ͍͔ • ֦ுػೳͱͯ͠ʮσʔλιʔεʯͷ֓೦Λಋೖͯ͠ɺίϝϯτจࣈྻ Ҏ֎͔Βಘͨ৘ใΛ౷߹͍ͨ͠
45. ໰୊2ɿ ݁ہίʔυ΍ ςετίʔυΛಡΉ
46. ղܾࡦ2ɿ ςετίʔυ͔Β υΩϡϝϯτΛ ੜ੒͢Δ
47. ςετίʔυ͔ΒυΩϡϝϯτΛੜ੒͢Δ • RubyͰ͸RSpecͱ͍͏ςεςΟϯάϥΠϒϥϦ͕޿͘࢖ΘΕ͍ͯΔ • RSpecʹ͸`—format documentation`ͱ͍͏Φϓγϣϯ͕͋Δ • exampleͷ৔߹ͱಉ༷ʹ֦ுػೳ͕RSpecΛσʔλιʔεͱͯ͠ར༻ ͠ɺӾཡ࣌ʹखॻ͖ͷυΩϡϝϯτͱϚʔδ͢Δ • Ҋ1ɿRSpecͷग़ྗΛར༻͢Δʢ࣮ߦඞཁʣ • Ҋ2ɿRSpecͷιʔείʔυΛύʔε͢Δʢ࣮ߦෆཁʣ
48. ໰୊3ɿ ܕ͕υΩϡϝϯτ ͱઐ༻πʔϧͰผ
49. ղܾࡦ3ɿ ެࣜͷܕʢRBSʣ ʹἧ͑Δ
50. ͷɺલʹ
51. Rubyͷܕࣄ৘ʹ͍͓ͭͯ͞Β͍ • ެࣜͷܕγεςϜͰ͋ΔRBSͱɺඇެࣜͷܕγεςϜͰ͋ΔSorbet ʢRBIʣ͕ଘࡏ͢Δ • RBSͱRBI͸ݱঢ়ඇޓ׵ͰผʑͷΤίγεςϜ͕ଘࡏ͢Δ • RBS͸ผϑΝΠϧʹهड़͢Δํ͕ࣜओྲྀʢޙड़ʣɺRBI͸ιʔείʔυ ಺ʹݴޠ಺DSLͱͯ͠هड़͢Δ • YARDʹ͸ಠࣗͷܕه๏ʢܕݕࠪͳͲ͸ͳ͠ʣ͕ଘࡏ͢Δ
52. RubyͷܕγεςϜͱυΩϡϝϯτͷ݉Ͷ߹͍ • SorbetʢRBIʣ͸ίϝϯτͱಉ͡ҐஔʹRubyίʔυͱͯ͠ॻ͘ • ඪ४Ͱ͸υΩϡϝϯτʹܕ৘ใΛදࣔͰ͖ͳ͍ • RBSʹ͸࠷ۙrbs-inlineͱ͍͏ํ͕ࣜੜ·ΕɺRubyϑΝΠϧ಺ʹܕ৘ ใΛهड़Ͱ͖ΔΑ͏ʹͳͬͨ • υΩϡϝϯτʹ͸൓ө͞Εͳ͍ • ࡞ऀతʹ͸YARDʹد͍͖͍ͤͯͨΒ͍͠
54. ૊Έ߹Θͤരൃʹ֦ுػೳج൫ͰରԠ͢Δ • ݸผͷϓϥάΠϯʢྫ͑͹RBI -> YARDʣ͸ଘࡏ͢Δ͕ɺͦΕΒ͕ݸ ผʹϝϯςφϯε͞ΕΔͷ͸େมͰޮ཰͕ѱ͍ • ܕγεςϜͱੜ੒͞ΕΔHTMLυΩϡϝϯτͷதؒʹRDocཱ͕ͭ͜ͱ Ͱ૊Έ߹Θͤͷ਺ΛݮΒ͢ʢLSPతͳൃ૝ʣ • ܕγεςϜ֦ுػೳ͕ܕ৘ใΛυΩϡϝϯτ޲͚ʹม׵ͯ͠ɺHTML ੜ੒෦෼͸RDocʹ೚ͤΔ
55. 2. ༗༻Խ
56. ͔ͤͬ͘ υΩϡϝϯτΛ ࡞ͬͯ΋ ݟͯ΋Β͑ͳ͍…
57. υΩϡϝϯτΛ Ͳ͏࢖ͬͯ΄͍͠ ͔
58. ΞϓϦέʔγϣϯ or ϥΠϒϥϦ
59. ΞϓϦέʔγϣϯʹ͓͚ΔυΩϡϝϯτ׆༻ • LSPʢLanguage Server ProtocolʣͰυΩϡϝϯτΛදࣔ͢Δ • https://microsoft.github.io/language-server-protocol/ speci fi cations/lsp/3.17/speci fi cation/ #textDocument_signatureHelp • Railsίϯιʔϧ͔ΒυΩϡϝϯτͷஅยΛදࣔͯ͠ɺΫϦοΫ͢Δͱ ؔ࿈͢ΔΦϯϥΠϯυΩϡϝϯτʹҠಈ͢Δʁ • υΩϡϝϯτΛMarkdownͰग़ྗͯ͠esa΍KibelaͳͲͱ࿈ܞ͢Δʁ
60. ϥΠϒϥϦʹ͓͚ΔυΩϡϝϯτ׆༻ • ੜ੒͞ΕͨHTMLυΩϡϝϯτ͔ΒREPLʢIRBʣΛىಈͰ͖Δ • ϥΠϒϥϦͷؾʹͳΔػೳΛ͙͢ࢼͤΔ • υΩϡϝϯτʹରԠ͢Δϝιου΍Ϋϥεʹؔ࿈͢Δςετίʔυ͕ ಡΊΔʢࡉ͔͍࢓༷Λ೺ѲͰ͖Δʣ
61. υΩϡϝϯτ͸ ·ͩਐԽͰ͖Δʂ
62. ·ͱΊ
63. ָ͍͠υΩϡϝϯςʔγϣϯΛ໨ࢦͯ͠ • ֦ுػೳج൫ʹΑΔπʔϧͷRDoc΁ͷ౷߹ • υΩϡϝϯςʔγϣϯΛָʹ͢ΔΞΠσΞ • υΩϡϝϯτΛॻ͘͜ͱ͕ใΘΕΔΑ͏ʹͳΔͨΊͷπʔϧͷվળ
64. େࣄͳ͜ͱ
65. ະ࣮૷
66. Ұ෦͸ ۙ೔࣮૷
67. https://www.ruby.or.jp/ja/news/20240821
68. https://www.ruby.or.jp/ja/news/20241030
69. ࠷ऴใࠂظݶ 2025೥3݄
70. ͕Μ͹Γ·͢ʂ