Submit Search
Upload
Sphinxでまとめる多言語環境APIドキュメント
•
0 likes
•
3,678 views
Iosif Takakura
Follow
SphinxでPythonとC#のドキュメントを書く話。DocFXとSphinxを連携させる。
Read less
Read more
Software
Report
Share
Report
Share
1 of 29
Download now
Download to read offline
Recommended
Unityでオニオンアーキテクチャ
Unityでオニオンアーキテクチャ
torisoup
DXとかDevOpsとかのなんかいい感じのやつ 富士通TechLive
DXとかDevOpsとかのなんかいい感じのやつ 富士通TechLive
Tokoroten Nakayama
Unityでオンラインゲーム作った話
Unityでオンラインゲーム作った話
torisoup
Unicode文字列処理
Unicode文字列処理
信之 岩永
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
OpenVRやOpenXRの基本的なことを調べてみた
OpenVRやOpenXRの基本的なことを調べてみた
Takahiro Miyaura
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
継続使用と新規追加したRedmine Plugin
継続使用と新規追加したRedmine Plugin
Mei Nakamura
Recommended
Unityでオニオンアーキテクチャ
Unityでオニオンアーキテクチャ
torisoup
DXとかDevOpsとかのなんかいい感じのやつ 富士通TechLive
DXとかDevOpsとかのなんかいい感じのやつ 富士通TechLive
Tokoroten Nakayama
Unityでオンラインゲーム作った話
Unityでオンラインゲーム作った話
torisoup
Unicode文字列処理
Unicode文字列処理
信之 岩永
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
OpenVRやOpenXRの基本的なことを調べてみた
OpenVRやOpenXRの基本的なことを調べてみた
Takahiro Miyaura
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
継続使用と新規追加したRedmine Plugin
継続使用と新規追加したRedmine Plugin
Mei Nakamura
イベント・ソーシングを知る
イベント・ソーシングを知る
Shuhei Fujita
新入社員のための大規模ゲーム開発入門 サーバサイド編
新入社員のための大規模ゲーム開発入門 サーバサイド編
infinite_loop
Pythonの理解を試みる 〜バイトコードインタプリタを作成する〜
Pythonの理解を試みる 〜バイトコードインタプリタを作成する〜
Preferred Networks
ソフトウェアにおける 複雑さとは何なのか?
ソフトウェアにおける 複雑さとは何なのか?
Yoshitaka Kawashima
OPC UAをオープンソースやフリーのソフトで遊んでみた
OPC UAをオープンソースやフリーのソフトで遊んでみた
ミソジ
インタフェース完全に理解した
インタフェース完全に理解した
torisoup
Redmineとgitの 連携利用事例
Redmineとgitの 連携利用事例
Tomohisa Kusukawa
オブジェクト指向できていますか?
オブジェクト指向できていますか?
Moriharu Ohzu
ドメイン駆動設計に15年取り組んでわかったこと
ドメイン駆動設計に15年取り組んでわかったこと
増田 亨
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
Tokoroten Nakayama
例外設計における大罪
例外設計における大罪
Takuto Wada
Guide To AGPL
Guide To AGPL
Mikiya Okuno
Pythonによる黒魔術入門
Pythonによる黒魔術入門
大樹 小倉
技術ブログを書こう
技術ブログを書こう
akira6592
マイクロサービスにおける非同期アーキテクチャ
マイクロサービスにおける非同期アーキテクチャ
ota42y
ネットワーク ゲームにおけるTCPとUDPの使い分け
ネットワーク ゲームにおけるTCPとUDPの使い分け
モノビット エンジン
プログラマが欲しい仕様書とは
プログラマが欲しい仕様書とは
Katsutoshi Makino
フィーチャモデルの描き方
フィーチャモデルの描き方
H Iseri
見よう見まねでやってみる2D流体シミュレーション
見よう見まねでやってみる2D流体シミュレーション
KLab Inc. / Tech
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
社内のマニュアルをSphinxで作ってみた
社内のマニュアルをSphinxで作ってみた
Iosif Takakura
DocFXで脱Excel方眼紙!
DocFXで脱Excel方眼紙!
Iosif Takakura
More Related Content
What's hot
イベント・ソーシングを知る
イベント・ソーシングを知る
Shuhei Fujita
新入社員のための大規模ゲーム開発入門 サーバサイド編
新入社員のための大規模ゲーム開発入門 サーバサイド編
infinite_loop
Pythonの理解を試みる 〜バイトコードインタプリタを作成する〜
Pythonの理解を試みる 〜バイトコードインタプリタを作成する〜
Preferred Networks
ソフトウェアにおける 複雑さとは何なのか?
ソフトウェアにおける 複雑さとは何なのか?
Yoshitaka Kawashima
OPC UAをオープンソースやフリーのソフトで遊んでみた
OPC UAをオープンソースやフリーのソフトで遊んでみた
ミソジ
インタフェース完全に理解した
インタフェース完全に理解した
torisoup
Redmineとgitの 連携利用事例
Redmineとgitの 連携利用事例
Tomohisa Kusukawa
オブジェクト指向できていますか?
オブジェクト指向できていますか?
Moriharu Ohzu
ドメイン駆動設計に15年取り組んでわかったこと
ドメイン駆動設計に15年取り組んでわかったこと
増田 亨
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
Tokoroten Nakayama
例外設計における大罪
例外設計における大罪
Takuto Wada
Guide To AGPL
Guide To AGPL
Mikiya Okuno
Pythonによる黒魔術入門
Pythonによる黒魔術入門
大樹 小倉
技術ブログを書こう
技術ブログを書こう
akira6592
マイクロサービスにおける非同期アーキテクチャ
マイクロサービスにおける非同期アーキテクチャ
ota42y
ネットワーク ゲームにおけるTCPとUDPの使い分け
ネットワーク ゲームにおけるTCPとUDPの使い分け
モノビット エンジン
プログラマが欲しい仕様書とは
プログラマが欲しい仕様書とは
Katsutoshi Makino
フィーチャモデルの描き方
フィーチャモデルの描き方
H Iseri
見よう見まねでやってみる2D流体シミュレーション
見よう見まねでやってみる2D流体シミュレーション
KLab Inc. / Tech
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
What's hot
(20)
イベント・ソーシングを知る
イベント・ソーシングを知る
新入社員のための大規模ゲーム開発入門 サーバサイド編
新入社員のための大規模ゲーム開発入門 サーバサイド編
Pythonの理解を試みる 〜バイトコードインタプリタを作成する〜
Pythonの理解を試みる 〜バイトコードインタプリタを作成する〜
ソフトウェアにおける 複雑さとは何なのか?
ソフトウェアにおける 複雑さとは何なのか?
OPC UAをオープンソースやフリーのソフトで遊んでみた
OPC UAをオープンソースやフリーのソフトで遊んでみた
インタフェース完全に理解した
インタフェース完全に理解した
Redmineとgitの 連携利用事例
Redmineとgitの 連携利用事例
オブジェクト指向できていますか?
オブジェクト指向できていますか?
ドメイン駆動設計に15年取り組んでわかったこと
ドメイン駆動設計に15年取り組んでわかったこと
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
例外設計における大罪
例外設計における大罪
Guide To AGPL
Guide To AGPL
Pythonによる黒魔術入門
Pythonによる黒魔術入門
技術ブログを書こう
技術ブログを書こう
マイクロサービスにおける非同期アーキテクチャ
マイクロサービスにおける非同期アーキテクチャ
ネットワーク ゲームにおけるTCPとUDPの使い分け
ネットワーク ゲームにおけるTCPとUDPの使い分け
プログラマが欲しい仕様書とは
プログラマが欲しい仕様書とは
フィーチャモデルの描き方
フィーチャモデルの描き方
見よう見まねでやってみる2D流体シミュレーション
見よう見まねでやってみる2D流体シミュレーション
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Similar to Sphinxでまとめる多言語環境APIドキュメント
社内のマニュアルをSphinxで作ってみた
社内のマニュアルをSphinxで作ってみた
Iosif Takakura
DocFXで脱Excel方眼紙!
DocFXで脱Excel方眼紙!
Iosif Takakura
sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm
sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm
Takeshi Komiya
世界のSphinx事情 @ SphinxCon JP 2015
世界のSphinx事情 @ SphinxCon JP 2015
Takayuki Shimizukawa
TypeScriptで作る型安全FirefoxOSアプリ
TypeScriptで作る型安全FirefoxOSアプリ
progre
Zappa で Serverless CMS を作ってみる
Zappa で Serverless CMS を作ってみる
Iosif Takakura
Erlang and I and Sphinx.
Erlang and I and Sphinx.
Yoshiki Shibukawa
Why python
Why python
TeppeiAkada1
Why python
Why python
TeppeiAkada1
Goで始める言語処理系実装入門
Goで始める言語処理系実装入門
虎の穴 開発室
APIドキュメントの話 #sphinxjp
APIドキュメントの話 #sphinxjp
Takeshi Komiya
農業とITをOSSで
農業とITをOSSで
Bus Hato
「Python言語」はじめの一歩 / First step of Python
「Python言語」はじめの一歩 / First step of Python
Takanori Suzuki
シンボルフォント — それは、新しい画像形式
シンボルフォント — それは、新しい画像形式
Tsutomu Kawamura
Pyconjp2014_implementations
Pyconjp2014_implementations
masahitojp
他人が書いたコードのリファレンスをSphinxで作る方法
他人が書いたコードのリファレンスをSphinxで作る方法
Takeshi Sugiyama
Atnd地域検索作ったよー
Atnd地域検索作ったよー
Ohishi Mikage
もっとドキュメントが日本語になりますように
もっとドキュメントが日本語になりますように
Takako Miyagawa
邪道Jenkins
邪道Jenkins
hazisarashi
CPythonを読もう
CPythonを読もう
Akira Nonaka
Similar to Sphinxでまとめる多言語環境APIドキュメント
(20)
社内のマニュアルをSphinxで作ってみた
社内のマニュアルをSphinxで作ってみた
DocFXで脱Excel方眼紙!
DocFXで脱Excel方眼紙!
sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm
sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm
世界のSphinx事情 @ SphinxCon JP 2015
世界のSphinx事情 @ SphinxCon JP 2015
TypeScriptで作る型安全FirefoxOSアプリ
TypeScriptで作る型安全FirefoxOSアプリ
Zappa で Serverless CMS を作ってみる
Zappa で Serverless CMS を作ってみる
Erlang and I and Sphinx.
Erlang and I and Sphinx.
Why python
Why python
Why python
Why python
Goで始める言語処理系実装入門
Goで始める言語処理系実装入門
APIドキュメントの話 #sphinxjp
APIドキュメントの話 #sphinxjp
農業とITをOSSで
農業とITをOSSで
「Python言語」はじめの一歩 / First step of Python
「Python言語」はじめの一歩 / First step of Python
シンボルフォント — それは、新しい画像形式
シンボルフォント — それは、新しい画像形式
Pyconjp2014_implementations
Pyconjp2014_implementations
他人が書いたコードのリファレンスをSphinxで作る方法
他人が書いたコードのリファレンスをSphinxで作る方法
Atnd地域検索作ったよー
Atnd地域検索作ったよー
もっとドキュメントが日本語になりますように
もっとドキュメントが日本語になりますように
邪道Jenkins
邪道Jenkins
CPythonを読もう
CPythonを読もう
More from Iosif Takakura
取り込んだネガ画像の色を変換する Python スクリプトを書いてみた
取り込んだネガ画像の色を変換する Python スクリプトを書いてみた
Iosif Takakura
Marp for VS Code で作る PowerPoint スライド
Marp for VS Code で作る PowerPoint スライド
Iosif Takakura
scikit-image でフィルムスキャナで取り込んだネガ画像をポジ化する
scikit-image でフィルムスキャナで取り込んだネガ画像をポジ化する
Iosif Takakura
Django 製 CMS Wagtail で Blog を作ってみる
Django 製 CMS Wagtail で Blog を作ってみる
Iosif Takakura
Django と Wagtail で作る Headless CMS
Django と Wagtail で作る Headless CMS
Iosif Takakura
技術的負債との戦い方
技術的負債との戦い方
Iosif Takakura
C#初心者がxamarinに手を出してみた
C#初心者がxamarinに手を出してみた
Iosif Takakura
Sphinxで同人誌を書いてみた
Sphinxで同人誌を書いてみた
Iosif Takakura
ようこそ先輩 - 2014年8月2日
ようこそ先輩 - 2014年8月2日
Iosif Takakura
Osuncが終わったら帰りは警察署に行きましょう
Osuncが終わったら帰りは警察署に行きましょう
Iosif Takakura
More from Iosif Takakura
(10)
取り込んだネガ画像の色を変換する Python スクリプトを書いてみた
取り込んだネガ画像の色を変換する Python スクリプトを書いてみた
Marp for VS Code で作る PowerPoint スライド
Marp for VS Code で作る PowerPoint スライド
scikit-image でフィルムスキャナで取り込んだネガ画像をポジ化する
scikit-image でフィルムスキャナで取り込んだネガ画像をポジ化する
Django 製 CMS Wagtail で Blog を作ってみる
Django 製 CMS Wagtail で Blog を作ってみる
Django と Wagtail で作る Headless CMS
Django と Wagtail で作る Headless CMS
技術的負債との戦い方
技術的負債との戦い方
C#初心者がxamarinに手を出してみた
C#初心者がxamarinに手を出してみた
Sphinxで同人誌を書いてみた
Sphinxで同人誌を書いてみた
ようこそ先輩 - 2014年8月2日
ようこそ先輩 - 2014年8月2日
Osuncが終わったら帰りは警察署に行きましょう
Osuncが終わったら帰りは警察署に行きましょう
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
7.
7 Sphinx使って起こったことSphinx使って起こったこと ドキュメントの技術的負債化 メンテナンスできる人がいない なので、素のHTMLで書き直すことになりそう…… 1
8.
8 Sphinxを使う場合にどう書く?Sphinxを使う場合にどう書く? 1. APIの内容を調べてごりごり書く? 2. コメントから生成するツールを使う? 私は、コメントから生成するツールを推します。 なぜなら、人間は間違う生き物だからです。 1
9.
9 で、今回は2つの環境のドキュメントを作りまで、今回は2つの環境のドキュメントを作りま す。す。 1. Pythonで書かれたDjangoのアプリ 2. C#で書かれたASP.NET
Coreのアプリ どちらも作りかけですが気にしないでください。 というか、2.のほうはテンプレートにコメント書いただけです。 1
10.
10 Djangoアプリのドキュメントを作るDjangoアプリのドキュメントを作る ここは普通にsphinx-apidocで生成します。 なお、Graphvizが入らないのでモデル図出力は断念しました。 (SSD128GBじゃできないことが多すぎます……) 1
11.
11 スクリーンショットスクリーンショット 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
21.
21 再度Sphinxを実行再度Sphinxを実行 とりあえず、namespaceだけの空っぽのドキュメントが。 振り返ってみると、extensionsに を入 れ忘れていました。 これを入れると無事ドキュメントができました。 ただし英語です! 1
22.
22 スクリーンショットその1スクリーンショットその1 1
23.
23 スクリーンショットその2スクリーンショットその2 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
25.
25 こうなりました……こうなりました…… 1
26.
26 終わりに終わりに 1
27.
27 なぜSphinxを選んだのかなぜSphinxを選んだのか 1. PDF出力が容易 DocFXはHTMLに出力したものを印刷用PDFにする 2. 表現力が高い DocFXはMarkdown 3.
拡張が多い 1
28.
28 こうなったらいいなぁ……こうなったらいいなぁ…… 以下の言語ののAPIドキュメントをSphinxで出力できたらいいなぁ。 Ruby Swift Kotlin Dart 1
29.
29 おしまいおしまい 1
Download now