Guidedog¶
一度書いて、わかりやすく説明し、ウェブにも紙にも公開する。
Guidedog は同じ reStructuredText または Markdown のファイルから、ドキュメントのウェブサイトと PDF の本を作ります。文章を書くのは一度だけで、二つの版の内容は Guidedog がそろえます。
プレーンテキストのファイルを渡すと、Guidedog がそこからウェブページと本のページを作ります。
できること¶
- ウェブサイト。 ナビゲーション、検索、コードのハイライト、ライトとダークのテーマを備えたページを、自由に変更できる Jinja テンプレートから作ります。
- PDF の本。 章、相互参照、図、表、脚注、索引を、言語ごとの規則に合わせて Typst が組版します。
- reStructuredText と Markdown。 ディレクティブ、ロール、toctree、相互参照は Sphinx の利用者が思うとおりに働き、MyST Markdown を並べて使うこともできます。
- 翻訳。 gettext のカタログでプロジェクトを他の言語に訳せます。中国語、日本語、韓国語、ヒンディー語の文章も、画面と紙の両方で正しく組まれます。
- 図、数式、API ページ。 Graphviz の図、LaTeX の数式、ソースコードから読み取る Odin の API リファレンス。
- わかりやすいエラー。 何が間違っているか、どこか、どう直すかをメッセージが伝えます。ビルドに失敗しても、前回の正しいサイトはそのまま残ります。
一つのプログラム¶
Guidedog は一つの実行ファイルです。Python の環境も、LaTeX のインストールも、テーマや拡張機能の別パッケージもいりません。設定は TOML ファイル一つで、テンプレートはプロジェクトの中にある、編集できる普通のファイルです。
外部に頼る部分もまだあります。Guidedog は Typst と Graphviz を組み込んでビルドできます。組み込んでいない場合は、システムにインストールされた typst と Graphviz のプログラムを使います。Linux と macOS では、libcurl などいくつかのシステムライブラリも使います。
一度書いて、両方を見る¶
左が reStructuredText で、右はそれから Guidedog がこのページに作ったものです。PDF ビルダーは同じ内容を本のページとして組みます。
.. note::
Guidedog は文章を一度だけ読みます。
*同じ* ファイルが **ウェブサイト** にも
**本** にもなります。
.. list-table::
:header-rows: 1
* - ビルダー
- 結果
* - ``html``
- ウェブサイト
* - ``pdf``
- PDF の本
同じ ファイルが ウェブサイト にも 本 にもなります。
| ビルダー | 結果 |
|---|---|
html |
ウェブサイト |
pdf |
PDF の本 |
紙での仕上がりの例として PDF 版のマニュアル があります。マニュアルのウェブサイトと同じファイルから作られています。
はじめに¶
最新のリリース からお使いのシステム用のアーカイブをダウンロードし、 guidedog を PATH に置いて、プロジェクトを作ります。
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
quickstart は conf.toml 、 index.rst 、編集できるテンプレートを書き出します。 serve は書いている間にサイトを作り直します。最初のプロジェクトは チュートリアル で順に説明しています。Guidedog をソースからビルドするには、Odin をインストールし、 リポジトリの説明 に従ってください。
設計の議論¶
Guidedog の設計上の決定は、番号付きの議論として書き残しています。問題、代わりの案、決定、根拠です。どれもウェブで読むことも、PDF でダウンロードすることもできます。