Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Sphinxでまとめる多言語環境APIドキュメント

852 views

Published on

SphinxでPythonとC#のドキュメントを書く話。DocFXとSphinxを連携させる。

Published in: Software
  • Be the first to comment

  • Be the first to like this

Sphinxでまとめる多言語環境APIドキュメント

  1. 1. 1 SphinxでSphinxで まとめるまとめる 多言語環境多言語環境 APIドキュメントAPIドキュメントin SphinxCon 2018 2018-11-28 Иосиф Такакура (Iosif Takakura) @huideyeren 1
  2. 2. 2 はじめにはじめに 1
  3. 3. 3 自己紹介自己紹介 東京都在住 今日は東京から来ました アパレル系子会社に勤めてます 雑食系ITエンジニア たまにPyCon JPのスタッフにも顔出してます 普段使う技術 .NET 本業ではこちらを使用 JavaScript/TypeScript Python Ruby 今作っているモノ Django + Vue.js + Xamarin.Formsで作ってます。 Excel方眼紙が嫌いです。 いいことを3つ書き留めるプチ日記「e-koto-3」 1
  4. 4. 4 今回のごめんなさい今回のごめんなさい 1. JavaScript/TypeScriptまで手が回りませんでした。 というか、そもそも必要だったのか…… 2. ほとんどC#です。 3. しかも、Xamarin.Formsではありません。ASP.NETです。 4. ドキュメントを一つにまとめられませんでした。 そこはintersphinx使うんでないかい? 1
  5. 5. 5 本題本題 1
  6. 6. 6 ドキュメント、どう作ってます?ドキュメント、どう作ってます? 1. Excel方眼紙にゴリゴリと 2. 素のHTMLで書く 3. ドキュメント生成ツールを使う 私はSphinxが使いたいですが、 仕方なくExcel方眼紙使ってます…… 1
  7. 7. 7 Sphinx使って起こったことSphinx使って起こったこと ドキュメントの技術的負債化 メンテナンスできる人がいない なので、素のHTMLで書き直すことになりそう…… 1
  8. 8. 8 Sphinxを使う場合にどう書く?Sphinxを使う場合にどう書く? 1. APIの内容を調べてごりごり書く? 2. コメントから生成するツールを使う? 私は、コメントから生成するツールを推します。 なぜなら、人間は間違う生き物だからです。 1
  9. 9. 9 で、今回は2つの環境のドキュメントを作りまで、今回は2つの環境のドキュメントを作りま す。す。 1. Pythonで書かれたDjangoのアプリ 2. C#で書かれたASP.NET Coreのアプリ どちらも作りかけですが気にしないでください。 というか、2.のほうはテンプレートにコメント書いただけです。 1
  10. 10. 10 Djangoアプリのドキュメントを作るDjangoアプリのドキュメントを作る ここは普通にsphinx-apidocで生成します。 なお、Graphvizが入らないのでモデル図出力は断念しました。 (SSD128GBじゃできないことが多すぎます……) 1
  11. 11. 11 スクリーンショットスクリーンショット 1
  12. 12. 12 手順手順 以下のコードを に書き加えて するだけ。 ただし、Djangoのプロジェクトの下にSphinxドキュメントのディレク トリを作っていることが前提。 import os import sys sys.path.insert(0, os.path.abspath('..')) import django os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings") django.setup() 実に簡単!! 1
  13. 13. 13 ASP.NET Coreのドキュメントを作るASP.NET Coreのドキュメントを作る Read The Docsが開発しているsphinx-autoapiを使います。 なお、sphinx-autoapiは以下の言語に対応しているようです。 1. Python 2. .NET 3. Golang 4. JavaScript 1
  14. 14. 14 ドキュメントを生成するその前にドキュメントを生成するその前に Microsoftが作っている.NET向けのドキュメンテーションツール、 DocFXが必要になります。 インストールは以下のコマンドを実行します。 (Windows:要Chocolatey) choco install docfx (mac:要Homebrew) brew install docfx インストールしたら、PATHを通しておきましょう。 なお、Visual Studio経由でもインストールでき、その方が楽ですが、 後でハマります! 1
  15. 15. 15 DocFXをインストールしたらDocFXをインストールしたら まずは、DocFXの設定。 こちらはVisual Studioで行います。 1. ソリューションに「クラスライブラリー」プロジェクトを作りま す。 2. NuGetで、 パッケージを追加します。 3. を編集します。 4. ビルドすると フォルダ内にドキュメントができることを確認 します。 なお、DocFXは二重に入りますが気にしないでください。 これが終わったら、DocFXをインストールしたプロジェクトの下に ディレクトリを作り、そこにSphinxプロジェクトを作ります。 1
  16. 16. 16 の編集の編集 ここで大事なのは、metadataのところのdestを設定することです。 { "metadata": [ { "src": [ { "files": [ "dotnet_vue.csproj" ], "exclude": [ "**/bin/**", "**/obj/**" ], "src": ".." } ], "dest": "docs/_api", "disableGitFeatures": false, "disableDefaultFilter": false } ], 中略 } ディレクトリに設定しておきましょう。 1
  17. 17. 17 コメントを書いていくコメントを書いていく .NETではXMLコメントという形式でコメントを書いていきます。 スラッシュ3個で作ります。 using Microsoft.AspNetCore; using Microsoft.AspNetCore.Hosting; namespace dotnet_vue { /// <summary> /// Program. /// </summary> public class Program { /// <summary> /// The entry point of the program, where the program control starts and ends. /// </summary> /// <param name="args">The command-line arguments.</param> public static void Main(string[] args) { CreateWebHostBuilder(args).Build().Run(); } /// <summary> /// Creates the web host builder. /// </ > DocFXを使う場合はコメントの中にMarkdownも書けます。 1
  18. 18. 18 Sphinx側の設定Sphinx側の設定 を以下のように設定します。 1. extensionsに と を追加 2. 以下のコードをファイルの最後に追加 autoapi_type = 'dotnet' autoapi_dirs = ['..'] ただし、最初は を入れ忘れていまし た。 1
  19. 19. 19 ここで直面した問題ここで直面した問題 ~/d/d/docs ❯❯❯ make html Running Sphinx v1.8.2 loading translations [ja]... 完了 loading intersphinx inventory from <a href=" " tar intersphinx inventory has moved: <a href=" " target=" /usr/local/lib/python2.7/site-packages/autoapi/extension.py:89: RemovedInSphinx20Warnin app.info(bold('[AutoAPI] ') + darkgreen('Loading Data')) [AutoAPI] Loading Data [AutoAPI] Reading files... [100%] /Users/yusuke/dotnet-vue/dotnet_vue.Docs/docfx.json /usr/local/lib/python2.7/site-packages/autoapi/extension.py:96: RemovedInSphinx20Warnin app.info(bold('[AutoAPI] ') + darkgreen('Mapping Data')) [AutoAPI] Mapping Data /usr/local/lib/python2.7/site-packages/autoapi/extension.py:100: RemovedInSphinx20Warni app.info(bold('[AutoAPI] ') + darkgreen('Rendering Data')) [AutoAPI] Rendering Data Extension error: No API objects exist. Can't continue make: *** [html] Error 2 https://docs.python.org/objects.inv... https://docs.python.org/objects.inv APIオブジェクトがない……? 1
  20. 20. 20 ここで、DocFXに戻ってみるここで、DocFXに戻ってみる がないとかなんだかで落ちる。 とりあえずの解決法:以下のコマンドを実行。 nuget install -OutputDirectory $TMPDIR SQLitePCLRaw.core -ExcludeVersion for docfx in /usr/local/Cellar/docfx/*; do cp "$TMPDIR/SQLitePCLRaw.core/lib/net45/SQLi この解決方法は を参考 に。 https://github.com/dotnet/docfx/issues/3389 1
  21. 21. 21 再度Sphinxを実行再度Sphinxを実行 とりあえず、namespaceだけの空っぽのドキュメントが。 振り返ってみると、extensionsに を入 れ忘れていました。 これを入れると無事ドキュメントができました。 ただし英語です! 1
  22. 22. 22 スクリーンショットその1スクリーンショットその1 1
  23. 23. 23 スクリーンショットその2スクリーンショットその2 1
  24. 24. 24 残念なところ残念なところ reStructuredTextを書けません! ここに書いたコメント、全部消えました…… namespace dotnet_vue.Controllers { /// <summary> /// ** 天気 ** /// /// * A /// /// * 1 /// * 2 /// /// * B /// * C /// /// /// /// /// `ASP.NET <<a href=" `" target="_blank" rel="noreferrer" sty /// </summary> [Route("api/[controller]")] public class WeatherController : Controller { 中略 https://www.asp.net/> つまり、intersphinxは一工夫必要なようです…… 1
  25. 25. 25 こうなりました……こうなりました…… 1
  26. 26. 26 終わりに終わりに 1
  27. 27. 27 なぜSphinxを選んだのかなぜSphinxを選んだのか 1. PDF出力が容易 DocFXはHTMLに出力したものを印刷用PDFにする 2. 表現力が高い DocFXはMarkdown 3. 拡張が多い 1
  28. 28. 28 こうなったらいいなぁ……こうなったらいいなぁ…… 以下の言語ののAPIドキュメントをSphinxで出力できたらいいなぁ。 Ruby Swift Kotlin Dart 1
  29. 29. 29 おしまいおしまい 1

×