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

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)

VS2019でRiot.js

2019/07/21 Visutal Studio::VS2019
Visual Studio2019でNugetでriotを検索してもそれらしいのが出てきません。
ソリューション内に作ったjsフォルダを右クリックしたら「クライアント側のライブラリ」というメニューが目につきました。
riot2019002.png


<検索するタイプ>と表示されている枠にriotと入力。
riot2019003.png


勝手に@以降のバージョンが補完されました。
知らない間にRiotのバージョンも上がっています。
riot2019001.png


「インストール」ボタンを押すと下記のような感じ。
riot2019004.png

2019/05/19(日)Visual Studio 2019からCordovaが消える

やっと自宅のPCを買い替え、Visual Studio 2019をインストール。
Visual Studio 2019 = .NET Core 3.0と思っていたら、プルダウンに出てこず調べたら未だPreview段階。
ここでインストールしてもまた入れ直す必要出てくるので、それまでの間Cordovaで遊ぼうと思ったらVisual Studio 2019から Apache Cordovaは消えたようです。Visual Studio CodeもしくはVisual Studio 2017を使えと。ずいぶんと思い切ったことをしてくれますね…。

Visual Studio Codeを入れるかどうか迷ってます。

2019/05/06(月)MSTest、xUnit、NUnit

unittest010.png

Blazor電卓のテストプロジェクトを作成しようとテストでフィルターかけたら同じアイコンで4っつも抽出されました。
今まで使っていたのは.NET Frameworkだったので2番目のはず。
今回はBlazorで.NET Coreなので、MSTest、xUnit、NUnitの3択。

始めて目にする一番上のMSTestを試してみたら、見慣れた感じのプロジェクトができました。
使い慣れたこれでいこうかとも思いましたが、公式ドキュメントではなんとなくxUnit押しな感じ。
例題がちょうどCalculatorなのとやってることはMSTestと違わない(こだわりあるほどMSTestを使い込んでいない)ので、xUnitで行くことにしました。

2019/04/13(土)既存のプロジェクトをGitHubにあげる

一度やったはずなのにまた躓く…。
既にGitHub側もVisual Studio側も環境は整っている場合の手順のおさらい。

下準備

  • Visual Studioでプロジェクトを作成
  • ソース管理(ローカルリポジトリ)に追加しておく
  • GitHubでプロジェクト名と同じ名前のリポジトリを作成(ReadMeは追加しない)

GitHubで作成したリポジトリのアドレスをコピー

20190412002.png

Visual Studioのリポジトリの設定でリモートを追加

20190412001.png

20190412003.png

20190412004.png

20190412005.png


保存すれば後はいつもの作業…のはずが今回はおまけが…。
同期してプッシュしたらセキュリティの警告が表示されました。
20190412006.png


WebFormの新規プロジェクトで作成したばかりでほとんど修正していないのに何故?と思い確認したら、bootstrapのバージョンが脆弱性含んだものになっていたようです。
20190412007.png

Nugetで何も考えずに更新かけたら3.4.1に上げたつもりが4.3.1にあがってしまい、デザインの微調整が必要になりました。
OK キャンセル 確認 その他