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
770
mdbookのプラグインを作る話
puripuri2100
February 25, 2021
Tweet
Share
More Decks by puripuri2100
See All by puripuri2100
絵文字は構文解析できるのか
puripuri2100
0
9
係り受け解析を用いた法律文書中の略称規定の解析についての報告
puripuri2100
0
54
気胸の胸部CTデータの可視化
puripuri2100
0
220
SATySFiで作成する構文解析器
puripuri2100
0
170
SATySFiの開発についての要望
puripuri2100
0
360
研究の場においてのRust 製ソフトウェアのバージョン管理について
puripuri2100
0
510
法律文書の自動解析
puripuri2100
1
580
汎用的なコードフォーマットライブラリの作成
puripuri2100
0
280
ユーザーがカスタマイズできるクラスファイル ―v0.0.x と v0.1.x それぞれでの実装 ―
puripuri2100
0
280
Other Decks in Technology
See All in Technology
Mocking in Rust Applications
taiki45
1
380
LLVM/ASMを使った有限体の高速実装
herumi
0
120
EitherT_with_Future
aoiroaoino
1
1.1k
Oracle Exadata Database Service(Dedicated Infrastructure):サービス概要のご紹介
oracle4engineer
PRO
0
9.5k
Oracle Cloud Infrastructure IaaS 新機能アップデート 2024/6 - 2024/8
oracle4engineer
PRO
0
110
AI活用したくてもできなかった不動産SaaSの今とこれから
nealle
0
250
サーバー管理しないサーバーサービスManaged DevOps Pool
kkamegawa
0
110
2024年版 運用者たちのLLM
nwiizo
3
540
20240906_JAWS_Yamanashi_#1_leap_beyond_the_AWS_all_certifications
tsumita
1
270
標準ライブラリの奥深アップデートを掘り下げよう!
logica0419
2
450
デジタル化・DX推進あるある
y150saya
0
240
Zero Data Loss Autonomous Recovery Service サービス概要
oracle4engineer
PRO
0
3.2k
Featured
See All Featured
Debugging Ruby Performance
tmm1
72
12k
The Language of Interfaces
destraynor
153
23k
Designing for Performance
lara
604
68k
Robots, Beer and Maslow
schacon
PRO
157
8.1k
What's new in Ruby 2.0
geeforr
340
31k
The World Runs on Bad Software
bkeepers
PRO
64
11k
YesSQL, Process and Tooling at Scale
rocio
167
14k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
246
1.3M
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
26
1.9k
For a Future-Friendly Web
brad_frost
174
9.3k
Raft: Consensus for Rubyists
vanstee
135
6.5k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
326
21k
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