Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
mdbookのプラグインを作る話
Search
puripuri2100
February 25, 2021
Technology
0
960
mdbookのプラグインを作る話
puripuri2100
February 25, 2021
Tweet
Share
More Decks by puripuri2100
See All by puripuri2100
法律文書の自動解析2024
puripuri2100
0
50
絵文字は構文解析できるのか
puripuri2100
0
79
係り受け解析を用いた法律文書中の略称規定の解析についての報告
puripuri2100
0
3k
気胸の胸部CTデータの可視化
puripuri2100
0
290
SATySFiで作成する構文解析器
puripuri2100
0
260
SATySFiの開発についての要望
puripuri2100
0
430
研究の場においてのRust 製ソフトウェアのバージョン管理について
puripuri2100
0
610
法律文書の自動解析
puripuri2100
1
900
汎用的なコードフォーマットライブラリの作成
puripuri2100
0
320
Other Decks in Technology
See All in Technology
名刺メーカーDevグループ 紹介資料
sansan33
PRO
0
930
Simplifying Cloud Native app testing across environments with Dapr and Microcks
salaboy
0
160
小学4年生夏休みの自由研究「ぼくと Copilot エージェント」
taichinakamura
0
710
[Codex Meetup Japan #1] Codex-Powered Mobile Apps Development
korodroid
2
770
新規事業におけるGORM+SQLx併用アーキテクチャ
hacomono
PRO
0
280
incident_commander_demaecan__1_.pdf
demaecan
0
130
アイテムレビュー機能導入からの学びと改善
zozotech
PRO
0
150
RDS の負荷が高い場合に AWS で取りうる具体策 N 連発/a-series-of-specific-countermeasures-available-on-aws-when-rds-is-under-high-load
emiki
1
130
綺麗なデータマートをつくろう_データ整備を前向きに考える会 / Let's create clean data mart
brainpadpr
3
510
Claude Codeを駆使した初めてのiOSアプリ開発 ~ゼロから3週間でグローバルハッカソンで入賞するまで~
oikon48
7
2.2k
サイバーエージェント流クラウドコスト削減施策「みんなで金塊堀太郎」
kurochan
3
1.7k
プロダクトのコードから見るGoによるデザインパターンの実践 #go_night_talk
bengo4com
1
2.5k
Featured
See All Featured
The Language of Interfaces
destraynor
162
25k
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
20
1.2k
For a Future-Friendly Web
brad_frost
180
9.9k
Building a Modern Day E-commerce SEO Strategy
aleyda
44
7.8k
How to Think Like a Performance Engineer
csswizardry
27
2k
Why Our Code Smells
bkeepers
PRO
340
57k
Leading Effective Engineering Teams in the AI Era
addyosmani
5
420
Faster Mobile Websites
deanohume
310
31k
Side Projects
sachag
455
43k
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
RailsConf 2023
tenderlove
30
1.2k
Designing for humans not robots
tammielis
254
26k
Transcript
mdbook のプラグインを作る話 Rust LT 会 @puripuri2100 2021/2/25
自己紹介 所属 開成学園開成高等学校 学年 高校二年 普段やってること SAT YSFIのパッケージ作成・Rust でのパーサー の作成など
twitter @puripuri2100 GitHub @puripuri2100 e-mail
[email protected]
1
mdbook とは Rust 界隈で大きめの文書を作るときに頻繁に使われるツール (rust-lang 公式がメンテしている) 。 ファイルの path と文章構造を対応させた
SUMMARY ファイルを 基に、markdown ファイル群を HTML ファイル群に変換するソフ トウェア。 詳しい使い方は公式ドキュメントの https://rust-lang.github.io/mdBook/index.html を読みましょう。 2
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 3
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 プラグインにはプリプロセッサと代替バックエンドの 2 種類が ある。 3
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 プラグインにはプリプロセッサと代替バックエンドの 2 種類が ある。 book.tomlに書く設定によってどちらで呼び出すのか指定できる。
[preprocessor.<name>]と書くとプリプロセッサを呼び出し、 [output.<name>]と書くと代替バックエンドを呼び出す。 3
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 プラグインにはプリプロセッサと代替バックエンドの 2 種類が ある。 book.tomlに書く設定によってどちらで呼び出すのか指定できる。
[preprocessor.<name>]と書くとプリプロセッサを呼び出し、 [output.<name>]と書くと代替バックエンドを呼び出す。 今回自分が作ったのは、 「markdown ファイルから SAT YSFIのド キュメントファイルを生成する」代替バックエンド。 https://github.com/puripuri2100/mdbook-satysfi 3
代替バックエンドの作り方 stdinから JSON 形式で設定などが与えられるので、mdbook のラ イブラリの方で提供されている RenderContext::from_jsonという関 数を用いることでデータ構造に自動で直してくれる。 4
代替バックエンドの作り方 stdinから JSON 形式で設定などが与えられるので、mdbook のラ イブラリの方で提供されている RenderContext::from_jsonという関 数を用いることでデータ構造に自動で直してくれる。得られる データの種類: •
book.tomlに書いてあるものを toml::Value構造にしたもの • 現在位置や生成先の PathBuf • SUMMARY.mdの中の文章構造と、それに対応するファイルの中身 • タイトルや著者名などの book に関するデータ • build 時に使う設定(指定されたファイルが存在しない場合 に自動生成するかしないか、など) • 埋め込む Rust のコードの Edition が何か、という情報 4
ハマりどころその 1 基本的には得られるデータを上手いこと弄って変換して出力すれ ば作れるが、ハマったところがあるので紹介 5
ハマりどころその 1 基本的には得られるデータを上手いこと弄って変換して出力すれ ば作れるが、ハマったところがあるので紹介 1. markdown ファイルの中身が既に得られている← path を 使ってファイル先を読みにいかなくて良い
5
ハマりどころその 1 基本的には得られるデータを上手いこと弄って変換して出力すれ ば作れるが、ハマったところがあるので紹介 1. markdown ファイルの中身が既に得られている← path を 使ってファイル先を読みにいかなくて良い
2. data.book.iter()でファイル構造を iterator にできるので、わ ざわざ再帰関数を書く必要はない 5
テキストを出力したい形式に変換する markdown テキストを解析するのには pulldown-cmarkクレートを 用いるのが良い mdbook 本体も使用していて解析結果を統一できるうえに、かな り解析が早く、タグの場合分けによって出力結果を切り変えるの が楽 6
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 7
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 基本的に HTML のコードかどうかは「1
行単位」でしか教えてく れない 7
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 基本的に HTML のコードかどうかは「1
行単位」でしか教えてく れない <!-- <p> hoge --> <span style="background-color: #0099FF" class="foo">fuga</spam> 7
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 基本的に HTML のコードかどうかは「1
行単位」でしか教えてく れない <!-- <p> hoge --> <span style="background-color: #0099FF" class="foo">fuga</spam> コメントの中の HTML タグへの対処や、途中で改行されている HTML タグへの対処などは、正規表現を使って場合分けをしたり、 現在の状態を変化させながら場合分けをしたりする必要があって かなり大変 7
ハマりどころその 2(解決策) markdown に埋め込まれた HTML コードごと HTML コードに変換 して、変換後のコードを解析すれば楽になる! 8
ハマりどころその 2(解決策) markdown に埋め込まれた HTML コードごと HTML コードに変換 して、変換後のコードを解析すれば楽になる! ただし、&が&になり、<が<に、>が>に自動で変換されて
いるので、replaceメソッドを使って置き換える必要がある 8
ハマりどころ 3 ソースコード挿入に関して mdbook 独自拡張が存在する1ので、 なんとかしないといけない 1https://rust-lang.github.io/mdBook/format/mdbook.html 9
ハマりどころ 3 ソースコード挿入に関して mdbook 独自拡張が存在する1ので、 なんとかしないといけない {{#include file.rs}}のようにすると file.rsを読み込むような拡 張に
関しては、手書きパーサーで頑張りました(力技) 将来的にはここら辺を簡単に処理してくれる関数を公式が提供し てくれると嬉しいですね 1https://rust-lang.github.io/mdBook/format/mdbook.html 9
まとめ • book を作るのに良く使う mdbook には拡張機能を自分で作 る機能がある • 公式ライブラリ提供の関数を使えば作成者は変換プロセスだ けに集中できる
• ハマりどころがいくつかある • HTML コードへの対処がかなり難しいので、一旦全部 HTML コードに変換するのがオススメ • mdbook の独自拡張については結構頑張る必要がある 10