Support #2255

[English version] Sphinxを用いたドキュメント作成方法の整理

Added by Kenji Maruyama almost 4 years ago. Updated over 3 years ago.

Status:完了チェック待ちStart date:05/27/2014
Priority:NormalDue date:
Assignee:Kenji Maruyama% Done:

90%

Category:-Estimated time:1.00 hour
Target version:-

Description

http://redmine.groonga.org/issues/2204 の English version になります。

下書き・編集はwiki: http://redmine.groonga.org/projects/mroonga/wiki/How_to_make_document_using_Sphinx にて行います。


Subtasks

Support #2572: Developer's guide ドキュメントの修正完了チェック待ちKenji Maruyama

History

#1 Updated by Kenji Maruyama almost 4 years ago

  • Tracker changed from Feature to Support

#2 Updated by Kenji Maruyama almost 4 years ago

  • Estimated time set to 2.00

#3 Updated by Kenji Maruyama over 3 years ago

  • Status changed from 新規 to 完了チェック待ち
  • % Done changed from 0 to 90

#4 Updated by Susumu Yata over 3 years ago

ざっと途中まで読んで,なんとなく引っかかったところだけコメントを書きます.

  • BTS
    • 何の略かわかりにくいように思うので,最初は Bug Tracking System (BTS) とした方がいいんじゃないかと思います.
  • Generally speaking
    • 自分達のことなので,ちょっと大袈裟な気がします.
  • Roadmaps
    • これは Roadmap が正しいと思います.
  • git, github
    • ロゴは git, github ですが,文書においては Git, GitHub が使われているようです.
  • please make clone in read/write mode, and then commit and push please
    • 最後の please が余計ですかね.
  • mroonga
    • Mroonga ですね.
  • cutter
    • Cutter ですかね.
  • ReStructuredText
    • reStructuredText っぽいです.

全般的に内容が古くなってしまっているようなので,このままで大丈夫なのか気になりました.

#5 Updated by Kenji Maruyama over 3 years ago

http://redmine.groonga.org/issues/2255#note-4

レビューありがとうございます。

ほぼ Developer's guide の修正に関しての修正なので 別チケットにします。

#6 Updated by Susumu Yata over 3 years ago

8.11. Adding and updating documents

We use Sphinx for the documentation of mroonga.

-> We use Sphinx for documentation of Mroonga.

the を付けると文書化じゃなくて文書という意味に感じてしまいます.

We write documents in ReStructuredText format and we convert them to HTML.

-> We write documents in the reStructuredText format and convert them to HTML.

主語が同じなので後ろの we は取り除いた方がすっきりします.

The source files of documents are files having .rst extension in "doc/source" directory.

-> The source files of documents have .rst extension and are located in the "doc/source" directory of the Mroonga repository.

files are files だと違和感があるので,取り除いてみました. それから, HTML は別のリポジトリになることをわかりやすくするため, the Mroonga repository というのを追加してみました.

When you add or modify them, please try to build by "make html". and confirm that no syntax error happens.

-> When you add or update them, please try "make html" to confirm that there are no syntax errors.

ほかが update で統一されているので modify から update にしてみました. to build by だと意味がわからないので消してみました.

Documents are published in http://mroonga.org. Since we are using github's web site feature, they will be updated each time when HTML files are pushed to http://github.com/mroonga/mroonga.github.com repository. We push to mroonga.github.com repository after confirming the consistency between documents and current released version.

-> Documents are published in http://mroonga.org. Since we are using GitHub Project Pages, the web site is updated when HTML files are pushed to the http://github.com/mroonga/mroonga.github.com repository. We push added or updated HTML files to the repository after confirming the consistency between the documents and the current release version.

GitHub のドキュメントを見る限り Project Pages が正式名称のようです.

一応,ここまで読んでみて,あらためて日本語の方も読んでみたのですが,経験者が思い出しながら作業するには便利だけど,初心者にはかなり取っつきにくそうに思いました.

#7 Updated by Kenji Maruyama over 3 years ago

http://redmine.groonga.org/issues/2255#note-6

レビューありがとうございます。指摘された点について修正します。

経験者が思い出しながら作業するには便利だけど,初心者にはかなり取っつきにくそうに思いました.

具体的な手順、例を増やすことでもうすこしわかりやすくします。

#8 Updated by Susumu Yata over 3 years ago

すみません,チケットを間違えていたので消しました.

Also available in: Atom PDF