ヘルプなどドキュメントシステムに関して考える

[m-tmatma]

ヘルプなどドキュメントシステムに関して考える

現状 chm を使っているが、他にいい方法がないか考える

名前	URL	チケット
Gitbook	https://github.com/GitbookIO/gitbook	#105
Sphinx	http://sphinx-users.jp/gettingstarted/	#41 (comment)
pandoc	http://pandoc.org	なし

[jakenjarvis]

Sphinxについて所感などを。
この Issue41 の @KENCHjp さんへの回答は、専用のIssue出来たのでこちらで回答しますね。

学習工数が必要になりそうですが、他の成果物のメンテの工数との見合いでしょうか。

githubで普段Markdownを使ってる人であれば、reStructuredText自体の学習コストはそれほどかからないと思います。よく使うものも大体決まってきます。

５年ぐらい前に私が使ったときの所感としては、行間やスペースを空けないとうまく意図通りの表示にならなかったりすることが「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 です。順当にバージョンアップを重ねてますし、５年もたっていますので、今はもうちょっといろいろ良くなっているのではないかと思います。

[KageShiron]

Sphinxはchmも作れるんですね。良さそう。

サクラエディタの需要的にネットと切り離された環境で使う場合も結構ありそうなので、ローカルヘルプ対応は結構重要だと思ってます。

[KENCHjp]

Sphinx化のメリデメは @jakenjarvis さんの説明お聞きする限りなんとか乗り越えられそうですね。
SAKURA Editorのヘルプっておもいのほか工数かけてつくってあるので、
そのhtmlからさくっとコンバートとかできると、初めの一歩が楽そうです。

Sphinxに期待するのは、chmの次にも対応してくれそうなところですかね。
新しいモダンなヘルプえも、工数割かずに対応できるようになりそうですよね。

[m-tmatma]

https://github.com/jakenjarvis/ChatLoggerPlus/blob/master/sphinx/source/CautionObjectType.rst
を見る限り、内容を GitHub でもそのまま確認できるのでいい感じです。

以下のような感じで HTML Help (chmファイルの作成) までできました。
簡単に使えそうな感じです。

sphinx のインストール

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.

html ヘルプのプロジェクト作成

make htmlhelp

html ヘルプのコンパイル

"C:\Program Files (x86)\HTML Help Workshop\hhc.exe" build\htmlhelp\SAKURAEditordoc.chm

make を引数なしで実行

>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)

[jakenjarvis]

さすが @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ファイルから取ってきてくれていることがわかると思います。（階層の深さを３まで取るように指定している）

.. toctree::
    :maxdepth: 3

    Introduction

あと、Noteのところも出てない感じかな。

Tips

SphinxのreStructuredTextの書き方で悩んだときは、実際にそれをやっている文章を探して、その文章のrstソースを実際に見れば、どのように記載しているか把握できます。
例えば、先ほどの index のページを開き、右側にある「ソースコードを表示」をクリックすれば、実際のrstファイルの中身を確認できます。

Sphinxのマニュアル自体がSphinxで生成されているので、そのrstソースを見ると一番よくわかりますよ。

---

あれ、Sphinxのバージョン、日本語ドキュメントでは「Current version: 1.5.6」になってたけど、英語サイトだと1.8.1ですね。 @m-tmatma さんのmakeのログみて気が付きました（笑）

[m-tmatma]

vscode のプラグインがあるようです
https://www.pine4.net/Memo2/Article/Archive/reStructuredText-extension-for-Visual-Studio-Code-is-awesome

[m-tmatma]

全然調べてないが、 pandoc は reStructuredTextを入力も、出力もできるらしい
https://qiita.com/sky_y/items/80bcd0f353ef5b8980ee

[m-tmatma]

こんな記事あった
https://postd.cc/restructuredtext-vs-markdown-for-technical-documentation/

[m-tmatma]

python のへルプは Sphinx で作成しているみたい。
python のへルプは構造化されていて見やすい。

[m-tmatma]

Python 自身のヘルプに関するドキュメント
https://github.com/python/cpython/blob/master/Doc/README.rst

[m-tmatma]

Documenting Your Project Using Sphinx
https://pythonhosted.org/an_example_pypi_project/sphinx.html

[m-tmatma]

本が出てますね。
https://www.oreilly.co.jp/books/9784873118192/
(https://github.com/getstart-sphinx/getstart-sphinx)

[m-tmatma]

Sphinx で markdown が使えるらしい
https://speakerdeck.com/shirou/sphinx-with-markdown
(http://sphinx-users.jp/doc.html)

[berryzplus]

こないだなんかでヘルプ項目を追加したときに、全体を書き直したい衝動に駆られたんですが、簡単に整理できる方法があるならそれに乗っかったほうが作業量を少なく済ませられるのではないかと考えて我慢しました。

あと、PPAマクロの廃止を行うとすると、マクロ関数の説明にある「PPAでは引数を省略できない」という部分を削る必要がでてくるので、全体的にヘルプに手を加えなければならない可能性が出てきます。PPAマクロ廃止そのものはお手軽簡単修正なんですが、ヘルプの修正をどうするか結論が出なくて止まってる感じです。