DocFXでPDF作成

2019/08/15 DocFX
PDFに関してはなんとなくまだまだ発展途上の気がします。

wkhtmltopdfのインストール

第一の難関でした。
インストールし、環境変数にPathも追加しコマンドプロンプトでwkhtmltopdf -Vするとちゃんとバージョンが表示されるにも関わらず、下記のエラーが出てPDFが作成されない。
(環境はWin10でVS2019です)
wkhtmltopdf is a prerequisite when generating PDF. 
Please install it from https://wkhtmltopdf.org/downloads.html 
and save the executable folder to %PATH% first. 
Alternatively you can install it from https://chocolatey.org 
with `choco install wkhtmltopdf`.
ユーザーの環境変数ではなくシステムの環境変数に追加してもダメ。
VSを管理者として実行してみたらエラー解消。
一度解消すると、その後普通にVS起動してもエラー出ず。

pdfフォルダを作成し、中にtoc.ymlを置く

toc.yml

- name: Articles
  href: ../articles/toc.yml
- name: Api Documentation
  href: ../api/toc.yml

docfx.jsonにPDF関連のセクション追加

wkhtmltopdfのオプション

wkhtmltopdfのオプション一覧はこちら
docfx.jsonで指定する場合は"wkhtmltopdf":だけでなく"additionalArguments":が必要。

ページ番号を表示させる場合の例

...
"pdf": {
  "wkhtmltopdf": {
    "additionalArguments": "--footer-center [page]"
  },
  "content": [
...

PDF用CSSの調整

デフォルトのままのCSSだとIMPORTANTやWARNINGなどのデザインが崩れています。
しかも日本語化したはずのIMPORTANTやWARNINGもそのまま表示されています。
docfx pdf alert

デフォルトのPDF用テンプレートをエクスポート

こちらでWebサイト用のテンプレートをエクスポートしたのと同様、PDF用のデフォルトテンプレートをエクスポート。
docfx template export pdf.default
エクスポートが成功すると、pdf.default フォルダが追加されます。
pdf.default

カスタムテンプレートの作成

  • fontsフォルダがエクスポートしたpdf.defaultにはなかったので、defaultからコピー。
  • main.cssは元々空なので、エクスポートしたものをコピーしなくても同じ名前で作成した方が文字コードUTF-8になるかも。
  • token.json:唯一pdf.defaultからコピー。
docfxpdf025.png

docfx.jsonの編集

"pdf": {
  "template": [
    "pdf.default",
    "templates/pdf"
  ],

main.cssに追記

padding入れたり、アイコン(glyphicons)のコード変えたり(Web版と違うことに気づいた自分えらい)してかなり近づきましたが、ボーダーとフォントサイズが違いそう。
docfx pdf alert

表紙をつける

pdfフォルダ内にcover.mdを追加

docfxcover010.png

cover.mdに表紙用のスタイル適用

---
documentType: cover
---
# The real cover page title

表紙用スタイルをカスタマイズ

cover.html.primary.tmplを上書き
docfxcover020.png


詳しくはこちら

TOC(目次・Table of Contents)

下記の右側部分。デフォルトで作成される。
docfxpdf070.png

ページ番号が表示されないのは現在の仕様。ulタグのループになっている。
ページ番号表示しようとしたらテーブルにする気がする。

wkhtmltopdfのtocはページ番号付き。ただし最新の安定版ではバグによりtocが作成されない。

outline(しおり・ブックマーク)

DocFXのオプション

DefaultOutlinetoc.ymlを元にブックマーク作成?(デフォルト)
WkDefaultOutlineHTML内のhXを元にブックマーク作成
NoOutlineブックマークを作成しない
なぜかデフォルトのDefaultOutlineのリンクが変。
タイトルとジャンプ先ずれる。
スクロール位置によってジャンプ先が異なるような気もして安定しない。
似たような報告がされているけれど既にClose済み。Nugetのバージョンによるものかもしれません。
WkDefaultOutlineを使うかNoOutlineにする。

WkDefaultOutline

"pdf": {
  "outline": "WkDefaultOutline",
ジャンプ先はきれいに安定するようになりましたが…
docfxpdf050.png

「重要」「警告」などはh5で囲まれていたはず。勘弁してください状態。
試しにアラートの前にh2とh3を追加しアウトラインを3層までに制限してみました。
"pdf": {
  "outline": "WkDefaultOutline",
  "wkhtmltopdf": {
    "additionalArguments": "--footer-center [page] --outline-depth 3"
  },
docfxpdf060.png

これで使い物になるかどうかは使う人の判断で(^^;)。
※hXタグから自動で作成されるため、docfx.json内のtocTitleオプションも無視されます。
「Table of Contents」を日本語にしたい場合は、テンプレート(toc.html.tmpl)を日本語化しましょう。
docfxpdf070.png

コメントからドキュメント作成

2019/07/25 Visutal StudioDocFX
クラスや公開プロパティ、メソッドに付ける /// コメントからドキュメントを作成する一番楽な方法

Nugetを使いましょう

docfx010.png

docfx.console で検索

docfx020.png

インストール

docfx030.png

プロジェクトをビルドすると赤枠で囲んだ部分が勝手に追加されます。

docfx040.png

_siteの中にHTML版ドキュメントが作成されている

GitHub等でなんとなく見覚えのあるサイトが立ち上がります(^^;)。
docfx050.png

PDFにするにはdocfx.jsonをいじる必要ありますが、HTMLだけならデフォルトで大丈夫。

コードを変更しビルドする度にドキュメントが更新されます。
いくらずぼらな人間でもこれくらいならメンテできそう。
より良いドキュメントを目指すならsummaryとreturns以外のタグも覚えましょう。

※マークダウンファイルも追加されますが、日本語で編集する場合は文字コードをUTF-8に変える必要あり。

テンプレートのカスタマイズ(日本語化)

デフォルトのテンプレートをエクスポート

cmdでプロジェクトのルート(docfx.jsonファイルのある場所)に移動し下記のコマンドを実行
docfx template export default
※nugetでインストールした場合はPathが通っていないのでdocfxの前にパスを追加必要。
インストール場所が分からない場合はソリューションエクスプローラーで依存関係→NuGet→docfx.consoleを選択しプロパティで探す。実際にフォルダを開き、exeの場所を確認。
エクスポートが成功すると、下記のようなフォルダが作成される。
docfx060.png

token.jsonをコピー

pdf用のテンプレートと区別がつきやすいようにhtmljaとしましたが、エクスポートしたテンプレート名+jaの方が良かったかも。フォルダ名は任意です(docfx.jsonでフォルダ名指定)。
ここではhtmljaで通します。
docfx065.png

token.jsonを編集

そのままだと日本語を入れると文字化けするので、文字コードをユニコードに変更
docfx070.png

docfx080.png

key:valueのvalue側を日本語に。
  "fieldsInSubtitle": "フィールド",
  "propertiesInSubtitle": "プロパティ",
  "methodsInSubtitle": "メソッド",
  "eventsInSubtitle": "イベント",

docfx.jsonの編集

    "template": [
      "default"
    ],

    "template": [
      "default",
      "templates/htmlja"
    ],

Enter here to filter...を書き換える

一番日本語化したかったEnter here to filterがtoken.jsonに無いんですけど…。
しょうがないのでエクスポートしたテンプレートの下でfilterでグレップ。
toc.html.tmplがヒット。これもtoken.jsonと同じようにhtmljaフォルダ内にコピーし、必要個所を日本語に変更、文字コードをユニコードに変えて保存。

IN THIS ARTICLEを書き換える

上記と同じ操作を繰り返す。ただし今度のファイル(docfx.js)はstylesフォルダの下にあるので、htmljaフォルダ側でもstylesフォルダを作成し、その中にペースト。
最終的には下記のような形。
docfx090.png

おまけ

stylesフォルダ内には空のmain.cssファイルが用意されているので、上書きしたいCSSがある場合はhtmljaのstylesフォルダ内にmain.cssを新規追加ておくと便利。

Markdownでドキュメントを作成

articlesフォルダにひな形が既に作成されているので、初めてのマークダウン。

Markdown Editor

まずは、拡張機能のMarkdown Editorを入れる。
Markdown Editorのインストール


.mdファイルを開くと、画面が2分割され右側にプレビューが表示される。
残念ながらDFM(DocFX Flavored Markdown)には対応していないよう。
Markdown Editorプレビュー画面

上で編集したtoken.jsonにあった「IMPORTANT」や「WARNING」がちゃんと日本語になるかはビルドして確認。
DocFx日本語化

DocFX Flavored Markdownの記法

CommonMark
GFM(GitHub Flavored Markdown)
DFM(DocFX Flavored Markdown)
OK キャンセル 確認 その他