dashで自分のこもごものカオスなドキュメントをつくりたい


sphinxとdoc2dashを使う。
markdownもいいかもだけど。。

# 最初に

```sh:bash
bash-4.3$ pip search doc2dash
doc2dash (2.1.0)    - Convert docs to Dash.app
asdoc2dash (0.1.1)  - asdoc2dash is tools that convert from ASDoc to Dash Docset.
bash-4.3$ sudo pip install doc2dash
bash-4.3$ pip install unicode_ids
bash-4.3$ pip install yogosyu

bash-4.3$ sphinx-quickstart # autodocはy、あとはデフォ
bash-4.3$ make -e SPHINXOPTS="-D language='ja'" html
doc2dash -n mydashdocset.jp -i _build/html/_static/bash-4.3$ py.png -d ~/Documents/ _build/html/
```


# 整備していく

* docsetとして機能させるのにentryタイプをつける
	* https://kapeli.com/docsets#supportedentrytypes
	* sphinxのドキュメントにも指定すれば可能らしい
		* ClassesやModulesの生成
* 手順
	* sphinxのインストール
	* doc2dashのインストール
	* クイックスタートでテスト用のdocを作成
	* 日本語対応、unicode_idsをpip installしてconf.py変更
	* makeする（国際化のオプションつきの必要あり？？）
	* doc2dash変換する
	* 表示を確認する
	* alfreadからも検索してみる
* sphinxの使い方について、、
	* 案の定よくわからなくなって挫折するわけです
	* moduleやfunctionという属性がある
	* autodocでソースコードのディレクトリ指定して読み込める
	* 今回はソースコード話で直接記載したいけどわからない
	* sphinx-apidocを使うとソースコードベースで最初からジェネレートできるっぽい
	* autoClassとかいう記載もあるらしい。けど今回は直接記載したい。
	* autosummaryでさらにサマリーを作ることができるらしい。

indexディレクティブで索引に記載できた。
でも関数とかとして記載するのはどうするのか。

```rst

.. index:: hoge

.. index::
   single: execution; context
   single: どらえもん
   pair  : loop; statement
   triple: module; search; path

```

関数として登録できた。
デフォルトで出てくるpy-modindex.htmlに掲載するにはpy:moduleを使う。
（いつも気づいてからドキュメントに気づくという良くないフロー。）

http://docs.sphinx-users.jp/markup/toctree.html

> モジュールインデックスには py:module ディレクティブで指定されたエントリーが含まれます。

```rst

.. function:: testfunc()
.. py:module:: pytestfunc()


```

indexでもmoduleと同様のエントリー登録ができるのではないかという気がしてきた。

http://docs.sphinx-users.jp/markup/misc.html

	.. index:: <entries>


py:moduleの指定で生成されるインデックスが何なのか分かれば？
http://sphinx-users.jp/reverse-dict/system/doctree.html

```
<desc desctype="function" domain="py" noindex="False" objtype="function">
```

わからない。functionでpythonのドメインだけど、、このあとでindexが作られるみたいだし。もういいや。

http://docs.sphinx-users.jp/domains.html
http://docs.sphinx-users.jp/extdev/appapi.html#sphinx.application.Sphinx.add_object_type

> ドメインというのは、説明のためのマークアップ(reStructuredTextの ディレクティブ と ロール)と、プログラミング言語の構成部品と関連する オブジェクト へのリンクによってできています。ドメインに属するディレクティブとロール名は py:function などのように、 ドメイン:名前: という名前を持ちます。ドメインを使って、Pythonのモジュール索引のような、専用の索引作成もできます。

でも、ある程度分かってきた。
下記を見つつ、どのエントリーとして記録していくかだな。

https://kapeli.com/docsets#supportedentrytypes

annotation,keyword,define,word,tag,sample,categoryくらいかな。
category,tagが無難かな。

だめだ、、py:moduleでいっか。

追加のドメインもあるらしい。
http://docs.sphinx-users.jp/domains.html

拡張でテキストメモ用のドメインを作ればいいのだろうな。。
お、easycreateとか説明がある。。
https://bitbucket.org/klorenz/sphinxcontrib-domaintools

phpのやつ
http://pythonhosted.org/sphinxcontrib-phpdomain/#install

> ‘function’ cross-referenced with ‘func’
‘global’ cross-referenced with ‘global’
‘const’ cross-referenced with ‘const’
‘method’ cross-referenced with ‘meth’
‘class’ cross-referenced with ‘class’
‘attr’ cross-referenced with ‘attr’
‘exception’ cross-referenced with ‘exc’
‘namespace’ cross-referenced with ‘ns’
‘interface’ cross-referenced with ‘interface’

うまく動いてくれない。。
下記を見てうまくいった。

http://tk0miya.hatenablog.com/entry/2013/05/30/010010

```
.. php:function:: hogehoge($fuga)

   ほげほげする関数。

.. php:class:: Foo

   ふーふーするクラス。

   .. php:attr:: $bar

      ばー変数
```

でもやっぱりモジュールかな。。

微妙な仕上がり。。Alfreadから検索したりできるけど。。
約$30でDashのライセンスを購入するかどうか。。

```
es2015についてメモしていく
========================================

.. py:module:: ->
.. py:currentmodule:: ->
.. py:class:: Desc
   アロー関数
   ビルド後は無名関数

.. py:module:: =>
.. py:currentmodule:: =>
.. py:class:: Desc
   ファットアロー関数
   ビルド後は即時関数

.. py:module:: jsx
.. py:currentmodule:: jsx
.. py:class:: Desc
   htmlに見えても実はhtmlじゃない
   babelなどによってトランスパイルされてjavascriptに戻る
```

# 参考urls

## 拡張の一覧

https://bitbucket.org/birkenfeld/sphinx-contrib/

## doc2bashとsphinx

Docset Generation Guide - Kapeli
https://goo.gl/j9Xpdq

Dash.appにSphinxベースのドキュメントを追加する方法(日本語ドキュメントでもOKだよ) - プログラマ行進曲第二章
http://goo.gl/9TaFmV

Python の日本語ドキュメントをdashで利用できる形式に変換する(doc2dashを利用する) - Qiita
http://goo.gl/r1lh9O

doc2dash: Create docsets for Dash.app and Clones — doc2dash 2.1.0 documentation
https://goo.gl/xnh7cX

Usage — doc2dash 2.1.0 documentation
https://goo.gl/XeAAPY

es2016 sphinx ドキュメント - Google 検索
https://goo.gl/sl8Wwp

Dash User Guide - Kapeli
https://goo.gl/1E1zgq

プロジェクトを作る — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
http://goo.gl/g336o

索引に載せたい — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
http://goo.gl/d3Byyc

DashでMayaのコマンドリファレンスを参照する ·
http://goo.gl/bF2pTg

doc2dash_python-2.7ja - t
http://goo.gl/RDTttK

unicode_ids 2.0.5 : Python Package Index


各種Sphinx拡張 / Sphinx Extensions — 自作Sphinx拡張/My Sphinx Extensions


国際化 — Sphinx 1.4.4 ドキュメント


Stichwortverzeichnis — mydashdocset 0.1 Dokumentation


Sphinxを使ってみた - shouhの日記

## sphinxの使い方

Docset Generation Guide - Kapeli
https://goo.gl/SF4WiE

モジュール用のマークアップ — Sphinx v1.0 (hg) documentation
http://goo.gl/LDwEqk

Sphinx で自動的にAPIリファレンスを作成したい - Study08.net 対シンバシ殲滅用人型機動兵器
http://goo.gl/AWZbVD

Read the Docsでオープンソースのドキュメントをいい感じに書いてみる
http://goo.gl/rjCKeI

sphinx.ext.autodoc – docstringからのドキュメントの取り込み — Sphinx 1.4.4 ドキュメント
http://goo.gl/26jyr8

sphinx.ext.autosummary – autodocのサマリーの生成 — Sphinx 1.4.4 ドキュメント
http://goo.gl/UwRNPS

2014/06/21 Sphinxメンテナ日記: autosummaryは便利だね - 清水川Web
http://goo.gl/UXUDC4

Python の日本語ドキュメントをdashで利用できる形式に変換する(doc2dashを利用する) - Qiita
http://goo.gl/r1lh9O

pydocja / cpython-ja / ダウンロード — Bitbucket
https://goo.gl/hX675E