Sphinxでまとめる多言語環境APIドキュメント
•
0 likes•3,680 views
SphinxでPythonとC#のドキュメントを書く話。DocFXとSphinxを連携させる。
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Sphinxでまとめる多言語環境APIドキュメント
Similar to Sphinxでまとめる多言語環境APIドキュメント (20)
More from Iosif Takakura
Sphinxでまとめる多言語環境APIドキュメント
- 1. 1 SphinxでSphinxで まとめるまとめる 多言語環境多言語環境 APIドキュメントAPIドキュメントin SphinxCon 2018 2018-11-28 Иосиф Такакура (Iosif Takakura) @huideyeren 1
- 2. 2 はじめにはじめに 1
- 3. 3 自己紹介自己紹介 東京都在住 今日は東京から来ました アパレル系子会社に勤めてます 雑食系ITエンジニア たまにPyCon JPのスタッフにも顔出してます 普段使う技術 .NET 本業ではこちらを使用 JavaScript/TypeScript Python Ruby 今作っているモノ Django + Vue.js + Xamarin.Formsで作ってます。 Excel方眼紙が嫌いです。 いいことを3つ書き留めるプチ日記「e-koto-3」 1
- 4. 4 今回のごめんなさい今回のごめんなさい 1. JavaScript/TypeScriptまで手が回りませんでした。 というか、そもそも必要だったのか…… 2. ほとんどC#です。 3. しかも、Xamarin.Formsではありません。ASP.NETです。 4. ドキュメントを一つにまとめられませんでした。 そこはintersphinx使うんでないかい？ 1
- 5. 5 本題本題 1
- 6. 6 ドキュメント、どう作ってます？ドキュメント、どう作ってます？ 1. Excel方眼紙にゴリゴリと 2. 素のHTMLで書く 3. ドキュメント生成ツールを使う 私はSphinxが使いたいですが、 仕方なくExcel方眼紙使ってます…… 1
- 9. 9 で、今回は2つの環境のドキュメントを作りまで、今回は2つの環境のドキュメントを作りま す。す。 1. Pythonで書かれたDjangoのアプリ 2. C#で書かれたASP.NET Coreのアプリ どちらも作りかけですが気にしないでください。 というか、2.のほうはテンプレートにコメント書いただけです。 1
- 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 ASP.NET Coreのドキュメントを作るASP.NET Coreのドキュメントを作る Read The Docsが開発しているsphinx-autoapiを使います。 なお、sphinx-autoapiは以下の言語に対応しているようです。 1. Python 2. .NET 3. Golang 4. JavaScript 1
- 14. 14 ドキュメントを生成するその前にドキュメントを生成するその前に Microsoftが作っている.NET向けのドキュメンテーションツール、 DocFXが必要になります。 インストールは以下のコマンドを実行します。 (Windows:要Chocolatey) choco install docfx (mac:要Homebrew) brew install docfx インストールしたら、PATHを通しておきましょう。 なお、Visual Studio経由でもインストールでき、その方が楽ですが、 後でハマります！ 1
- 15. 15 DocFXをインストールしたらDocFXをインストールしたら まずは、DocFXの設定。 こちらはVisual Studioで行います。 1. ソリューションに「クラスライブラリー」プロジェクトを作りま す。 2. NuGetで、 パッケージを追加します。 3. を編集します。 4. ビルドすると フォルダ内にドキュメントができることを確認 します。 なお、DocFXは二重に入りますが気にしないでください。 これが終わったら、DocFXをインストールしたプロジェクトの下に ディレクトリを作り、そこにSphinxプロジェクトを作ります。 1
- 16. 16 の編集の編集 ここで大事なのは、metadataのところのdestを設定することです。 { "metadata": [ { "src": [ { "files": [ "dotnet_vue.csproj" ], "exclude": [ "**/bin/**", "**/obj/**" ], "src": ".." } ], "dest": "docs/_api", "disableGitFeatures": false, "disableDefaultFilter": false } ], 中略 } ディレクトリに設定しておきましょう。 1
- 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 Sphinx側の設定Sphinx側の設定 を以下のように設定します。 1. extensionsに と を追加 2. 以下のコードをファイルの最後に追加 autoapi_type = 'dotnet' autoapi_dirs = ['..'] ただし、最初は を入れ忘れていまし た。 1
- 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 ここで、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
- 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
- 26. 26 終わりに終わりに 1
- 27. 27 なぜSphinxを選んだのかなぜSphinxを選んだのか 1. PDF出力が容易 DocFXはHTMLに出力したものを印刷用PDFにする 2. 表現力が高い DocFXはMarkdown 3. 拡張が多い 1
- 29. 29 おしまいおしまい 1