Enviar pesquisa
Carregar
Sphinxでまとめる多言語環境APIドキュメント
•
0 gostou
•
3,678 visualizações
Iosif Takakura
Seguir
SphinxでPythonとC#のドキュメントを書く話。DocFXとSphinxを連携させる。
Leia menos
Leia mais
Software
Denunciar
Compartilhar
Denunciar
Compartilhar
1 de 29
Baixar agora
Baixar para ler offline
Recomendados
僕がつくった 70個のうちの48個のWebサービス達
僕がつくった 70個のうちの48個のWebサービス達
Yusuke Wada
MVC の Model を考える
MVC の Model を考える
tomo_masakura
シェーダだけで世界を創る!three.jsによるレイマーチング
シェーダだけで世界を創る!three.jsによるレイマーチング
Sho Hosoda
画像処理ライブラリ OpenCV で 出来ること・出来ないこと
画像処理ライブラリ OpenCV で 出来ること・出来ないこと
Norishige Fukushima
商流物流金流.pdf
商流物流金流.pdf
Zenji Kanzaki
DDD x CQRS 更新系と参照系で異なるORMを併用して上手くいった話
DDD x CQRS 更新系と参照系で異なるORMを併用して上手くいった話
Koichiro Matsuoka
組織にテストを書く文化を根付かせる戦略と戦術
組織にテストを書く文化を根付かせる戦略と戦術
Takuto Wada
C++のビルド高速化について
C++のビルド高速化について
AimingStudy
Recomendados
僕がつくった 70個のうちの48個のWebサービス達
僕がつくった 70個のうちの48個のWebサービス達
Yusuke Wada
MVC の Model を考える
MVC の Model を考える
tomo_masakura
シェーダだけで世界を創る!three.jsによるレイマーチング
シェーダだけで世界を創る!three.jsによるレイマーチング
Sho Hosoda
画像処理ライブラリ OpenCV で 出来ること・出来ないこと
画像処理ライブラリ OpenCV で 出来ること・出来ないこと
Norishige Fukushima
商流物流金流.pdf
商流物流金流.pdf
Zenji Kanzaki
DDD x CQRS 更新系と参照系で異なるORMを併用して上手くいった話
DDD x CQRS 更新系と参照系で異なるORMを併用して上手くいった話
Koichiro Matsuoka
組織にテストを書く文化を根付かせる戦略と戦術
組織にテストを書く文化を根付かせる戦略と戦術
Takuto Wada
C++のビルド高速化について
C++のビルド高速化について
AimingStudy
メタプログラミングって何だろう
メタプログラミングって何だろう
Kota Mizushima
コンテナの作り方「Dockerは裏方で何をしているのか?」
コンテナの作り方「Dockerは裏方で何をしているのか?」
Masahito Zembutsu
リンク機構を有するロボットをGazeboで動かす
リンク機構を有するロボットをGazeboで動かす
tomohiro kuwano
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
Takayuki Shimizukawa
目grep入門 +解説
目grep入門 +解説
murachue
オブジェクト指向できていますか?
オブジェクト指向できていますか?
Moriharu Ohzu
画像認識の初歩、SIFT,SURF特徴量
画像認識の初歩、SIFT,SURF特徴量
takaya imai
良い?悪い?コードコメントの書き方
良い?悪い?コードコメントの書き方
Shigenori Sagawa
tf,tf2完全理解
tf,tf2完全理解
Koji Terada
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
Yoshiki Hayama
恐怖!シェルショッカーの POSIX原理主義シェルスクリプト
恐怖!シェルショッカーの POSIX原理主義シェルスクリプト
Richie Shellshoccar
ドメイン駆動で開発する ラフスケッチから実装まで
ドメイン駆動で開発する ラフスケッチから実装まで
増田 亨
Marp入門
Marp入門
Rui Watanabe
プログラムの処方箋~健康なコードと病んだコード
プログラムの処方箋~健康なコードと病んだコード
Shigenori Sagawa
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Kohei Tokunaga
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
Takuto Wada
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
Pythonによる黒魔術入門
Pythonによる黒魔術入門
大樹 小倉
こわくない Git
こわくない Git
Kota Saito
自宅k8s/vSphere入門
自宅k8s/vSphere入門
富士通クラウドテクノロジーズ株式会社
社内のマニュアルをSphinxで作ってみた
社内のマニュアルをSphinxで作ってみた
Iosif Takakura
DocFXで脱Excel方眼紙!
DocFXで脱Excel方眼紙!
Iosif Takakura
Mais conteúdo relacionado
Mais procurados
メタプログラミングって何だろう
メタプログラミングって何だろう
Kota Mizushima
コンテナの作り方「Dockerは裏方で何をしているのか?」
コンテナの作り方「Dockerは裏方で何をしているのか?」
Masahito Zembutsu
リンク機構を有するロボットをGazeboで動かす
リンク機構を有するロボットをGazeboで動かす
tomohiro kuwano
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
Takayuki Shimizukawa
目grep入門 +解説
目grep入門 +解説
murachue
オブジェクト指向できていますか?
オブジェクト指向できていますか?
Moriharu Ohzu
画像認識の初歩、SIFT,SURF特徴量
画像認識の初歩、SIFT,SURF特徴量
takaya imai
良い?悪い?コードコメントの書き方
良い?悪い?コードコメントの書き方
Shigenori Sagawa
tf,tf2完全理解
tf,tf2完全理解
Koji Terada
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
Yoshiki Hayama
恐怖!シェルショッカーの POSIX原理主義シェルスクリプト
恐怖!シェルショッカーの POSIX原理主義シェルスクリプト
Richie Shellshoccar
ドメイン駆動で開発する ラフスケッチから実装まで
ドメイン駆動で開発する ラフスケッチから実装まで
増田 亨
Marp入門
Marp入門
Rui Watanabe
プログラムの処方箋~健康なコードと病んだコード
プログラムの処方箋~健康なコードと病んだコード
Shigenori Sagawa
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Kohei Tokunaga
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
Takuto Wada
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
Pythonによる黒魔術入門
Pythonによる黒魔術入門
大樹 小倉
こわくない Git
こわくない Git
Kota Saito
自宅k8s/vSphere入門
自宅k8s/vSphere入門
富士通クラウドテクノロジーズ株式会社
Mais procurados
(20)
メタプログラミングって何だろう
メタプログラミングって何だろう
コンテナの作り方「Dockerは裏方で何をしているのか?」
コンテナの作り方「Dockerは裏方で何をしているのか?」
リンク機構を有するロボットをGazeboで動かす
リンク機構を有するロボットをGazeboで動かす
エキスパートPythonプログラミング改訂3版の読みどころ
エキスパートPythonプログラミング改訂3版の読みどころ
目grep入門 +解説
目grep入門 +解説
オブジェクト指向できていますか?
オブジェクト指向できていますか?
画像認識の初歩、SIFT,SURF特徴量
画像認識の初歩、SIFT,SURF特徴量
良い?悪い?コードコメントの書き方
良い?悪い?コードコメントの書き方
tf,tf2完全理解
tf,tf2完全理解
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
恐怖!シェルショッカーの POSIX原理主義シェルスクリプト
恐怖!シェルショッカーの POSIX原理主義シェルスクリプト
ドメイン駆動で開発する ラフスケッチから実装まで
ドメイン駆動で開発する ラフスケッチから実装まで
Marp入門
Marp入門
プログラムの処方箋~健康なコードと病んだコード
プログラムの処方箋~健康なコードと病んだコード
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Pythonによる黒魔術入門
Pythonによる黒魔術入門
こわくない Git
こわくない Git
自宅k8s/vSphere入門
自宅k8s/vSphere入門
Semelhante a 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
Semelhante a 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を読もう
Mais de 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
Mais de 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
Baixar agora