Open m-tmatma opened 5 years ago
Sphinxについて所感などを。 この Issue41 の @KENCHjp さんへの回答は、専用のIssue出来たのでこちらで回答しますね。
学習工数が必要になりそうですが、他の成果物のメンテの工数との見合いでしょうか。
githubで普段Markdownを使ってる人であれば、reStructuredText自体の学習コストはそれほどかからないと思います。よく使うものも大体決まってきます。
5年ぐらい前に私が使ったときの所感としては、行間やスペースを空けないとうまく意図通りの表示にならなかったりすることが「Markdownで書いているときよりも多く感じた」ので、そこの「独特のクセ」が、気になるかもしれません。 ただ、それも慣れてしまえば、ほとんどMarkdownと変わらない感覚で使えました。
Sphinx自体の学習コストは、どうしても、だれか一人、最初の設定をする人がかかります。 Pythonにもまだ慣れてない当時の私の場合は、数日程度の時間をかける必要がありました。それでも、ドキュメントがしっかりしていたので、それほどハマることもありませんでした。(苦労した覚えはない)
参考までに、昔、使ったときのプロジェクトへのリンクを張っておきます。 https://github.com/jakenjarvis/ChatLoggerPlus/tree/master/sphinx これを、HTMLに吐き出して、GitHub Pagesにあげてる生成物が、 http://jakenjarvis.github.io/ChatLoggerPlus/ です。(デザイン部分は、テンプレートを標準のものから別のものへ変えてます)
/sphinx/source/
フォルダの下のrst拡張子のファイルが作成したreStructuredText文書です。
(github上で見ると、Markdownで表示しようとしちゃっているので、Rawで見てください)/sphinx/source/java/
フォルダの下に、Javaのソースコードのコメントから自動生成された文書も入ってます。(Sphinxは、C/C++プロジェクトのソースコードからのドキュメント自動生成もできます -> Sphinxドメイン)確かに、オンラインヘルプとローカルヘルプと、さらにWiki等を一つのリソースから生成できるのは楽できそうですね。
ですです。当時の私はAPIドキュメントと説明文書を一緒に扱えるようなものを探してSphinxにたどり着きました。
私が使ったのが Sphinx 1.2b3
で、最新版が Sphinx 1.5.6
です。順当にバージョンアップを重ねてますし、5年もたっていますので、今はもうちょっといろいろ良くなっているのではないかと思います。
Sphinxはchmも作れるんですね。良さそう。
サクラエディタの需要的にネットと切り離された環境で使う場合も結構ありそうなので、ローカルヘルプ対応は結構重要だと思ってます。
Sphinx化のメリデメは @jakenjarvis さんの説明お聞きする限りなんとか乗り越えられそうですね。 SAKURA Editorのヘルプっておもいのほか工数かけてつくってあるので、 そのhtmlからさくっとコンバートとかできると、初めの一歩が楽そうです。
Sphinxに期待するのは、chmの次にも対応してくれそうなところですかね。 新しいモダンなヘルプえも、工数割かずに対応できるようになりそうですよね。
https://github.com/jakenjarvis/ChatLoggerPlus/blob/master/sphinx/source/CautionObjectType.rst を見る限り、内容を GitHub でもそのまま確認できるのでいい感じです。
以下のような感じで HTML Help (chmファイルの作成) までできました。 簡単に使えそうな感じです。
pip install sphinx
C:\Python27\Scripts\sphinx-quickstart.exe
→ 質問に答える
>"C:\Python27\Scripts\sphinx-quickstart.exe"
Welcome to the Sphinx 1.8.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: SAKURA Editor
> Author name(s): SAKURA Editor development
> Project release []:
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: jp
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y
Note: imgmath and mathjax cannot be enabled at the same time. imgmath has been deselected.
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: y
Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
make htmlhelp
"C:\Program Files (x86)\HTML Help Workshop\hhc.exe" build\htmlhelp\SAKURAEditordoc.chm
>make
Sphinx v1.8.1
Please use `make target' where target is one of
html to make standalone HTML files
dirhtml to make HTML files named index.html in directories
singlehtml to make a single large HTML file
pickle to make pickle files
json to make JSON files
htmlhelp to make HTML files and an HTML help project
qthelp to make HTML files and a qthelp project
devhelp to make HTML files and a Devhelp project
epub to make an epub
latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
text to make text files
man to make manual pages
texinfo to make Texinfo files
gettext to make PO message catalogs
changes to make an overview of all changed/added/deprecated items
xml to make Docutils-native XML files
pseudoxml to make pseudoxml-XML files for display purposes
linkcheck to check all external links for integrity
doctest to run all doctests embedded in the documentation (if enabled)
coverage to run coverage check of the documentation (if enabled)
さすが @m-tmatma さん。 私なんかより、ずっと早い時間でそこまで出来たのですね(汗)
https://github.com/jakenjarvis/ChatLoggerPlus/blob/master/sphinx/source/CautionObjectType.rst を見る限り、内容を GitHub でもそのまま確認できるのでいい感じです。
このGitHubでの表示は注意です。 例えば、上記ページの実際のページはこんな感じです。細かい部分で違いが見て取れます。 http://jakenjarvis.github.io/ChatLoggerPlus/CautionObjectType.html
reStructuredTextとして正しく解釈していないようなので、「文章としてのチェック」や「内容の確認」程度ならこれでも構いませんが、「表示内容のチェック」は、やはりビルド後の内容を見なければならないです。
ざっと見た感じだと、他のrstファイルへのリンク部分が、出てません。 例えば、このindexのページを比較して見れば、よくわかると思います。 https://github.com/jakenjarvis/ChatLoggerPlus/blob/master/sphinx/source/index.rst http://jakenjarvis.github.io/ChatLoggerPlus/index.html
ソース上、以下のように記載すると、Introduction.rstへのリンクを張り、しかもページ内の章タイトルをIntroduction.rstファイルから取ってきてくれていることがわかると思います。(階層の深さを3まで取るように指定している)
.. toctree::
:maxdepth: 3
Introduction
あと、Noteのところも出てない感じかな。
SphinxのreStructuredTextの書き方で悩んだときは、実際にそれをやっている文章を探して、その文章のrstソースを実際に見れば、どのように記載しているか把握できます。 例えば、先ほどの index のページを開き、右側にある「ソースコードを表示」をクリックすれば、実際のrstファイルの中身を確認できます。
Sphinxのマニュアル自体がSphinxで生成されているので、そのrstソースを見ると一番よくわかりますよ。
あれ、Sphinxのバージョン、日本語ドキュメントでは「Current version: 1.5.6」になってたけど、英語サイトだと1.8.1ですね。 @m-tmatma さんのmakeのログみて気が付きました(笑)
全然調べてないが、 pandoc は reStructuredTextを入力も、出力もできるらしい https://qiita.com/sky_y/items/80bcd0f353ef5b8980ee
python のへルプは Sphinx で作成しているみたい。 python のへルプは構造化されていて見やすい。
Python 自身のヘルプに関するドキュメント https://github.com/python/cpython/blob/master/Doc/README.rst
Documenting Your Project Using Sphinx https://pythonhosted.org/an_example_pypi_project/sphinx.html
Sphinx で markdown が使えるらしい https://speakerdeck.com/shirou/sphinx-with-markdown (http://sphinx-users.jp/doc.html)
こないだなんかでヘルプ項目を追加したときに、全体を書き直したい衝動に駆られたんですが、簡単に整理できる方法があるならそれに乗っかったほうが作業量を少なく済ませられるのではないかと考えて我慢しました。
あと、PPAマクロの廃止を行うとすると、マクロ関数の説明にある「PPAでは引数を省略できない」という部分を削る必要がでてくるので、全体的にヘルプに手を加えなければならない可能性が出てきます。PPAマクロ廃止そのものはお手軽簡単修正なんですが、ヘルプの修正をどうするか結論が出なくて止まってる感じです。
ヘルプなどドキュメントシステムに関して考える
現状 chm を使っているが、他にいい方法がないか考える