オープンソースプロジェクトのドキュメントを管理する方法は？
私は成長するオープンソースプロジェクトの作成者です。現在、ドキュメンテーションを管理するための最良の方法を見つけようとしていらいらしています。私が検討したオプションは次のとおりです。
- HTMLウェブサイト
- Github Wiki
- GithubでホストされているMarkdownファイル
- すべてのドキュメントをGithub README.mdに配置する
ドキュメントはすでにMarkdownで記述されていますが、どのように利用できるようにするのかわかりません。ソースを分岐してタグを付けるのと同じように、ドキュメントを分岐してタグを付けることができるので、私は本当にGitに惹かれています。
Markdownライブラリを使用して、MarkdownをHTMLに変換し、スタイル付きのWebサイトに表示できます。変更があったときはいつでもウェブサイトに変更をアップロードする必要があり、ドキュメントのさまざまな「タグ」をすべて管理することは困難です。
Github Wiki（私の知る限り）は、現在のブランチによって変化しません。そのため、私はいつでも、Github Wikiフォームでドキュメントの「マスター」バージョンしか持つことができませんでした。
すべてをGithubに配置するREADMEはすごくいいです。分岐とタグ付けはできますが、使用するのは少し面倒で、簡単なナビゲーションには向いていません。
私はいくつかの素晴らしい解決策を見逃していますか？他にどのようなオプションがありますか？
私が言えることの1つは、ドキュメントは（必要なマークアップを使用して）ソースコードファイルになければならず、それらからドキュメントが自動的に生成されるということです。
少なくともサイトでは、ソースパッケージの一部としてドキュメントのフォーマット済みダウンロードを生成できるため、ユーザーは特定のドキュメントツールを必要としません
他の誰かが関数を修正/追加してから、同じファイル内のすぐ隣にあるマークアップドキュメントを編集/追加する可能性は低いかもしれませんが、別のドキュメントリポジトリでまったく異なるファイルを見つけて同じことを行う可能性はわずかですゼロ未満。
必要に応じて、大きなテキストブロックを含むtutorial.hを常に作成できますが、ソースの一部として扱います。
プロジェクトがライブラリの場合、コード自体のコメントからAPI構文を文書化するために、javadocスタイルのドキュメントに勝るものはありません。
チュートリアル、使用例などのドキュメントについては、wiki形式を使用することを強くお勧めします。私が見た他のプロジェクトでは、ブランチごとに別々のページがあります。新しいブランチを開始するときは、変更されていないものを新しいページにコピーし、そこから更新します。
Wikiを推奨する理由は逸話ですが、個人的な経験によるものです。私は何度かオープンソースプロジェクトのドキュメントの更新に貢献しましたが、それらはすべてwikiにありました。何かを理解しようとしていて、ドキュメントが誤解を招く、または役に立たない場合は、それを理解した後、ドキュメントにいる間にwikiを更新し、心の中で新鮮になります。少なくとも、1年か2年後に自分でもう一度調べなければならない可能性が高いことを知っているので、返済の意味からではないでしょう。
Wikiがない場合、ドキュメントの生成方法、保存場所の把握、ソース管理からの最新情報の取得、編集の方法、実際の編集、およびエントリへの障壁が高すぎるメーリングリストをナビゲートしてパッチを受け入れます。
ドキュメントを厳しく管理したい場合は、更新するのはあなただけなので、必ず、最も快適なものを使用してください。コミュニティへの参加を奨励したい場合は、wikiを使用してください。
ソースでホストされているMarkdownファイルは非常にうまく機能します。
たとえば、RSTベースの docutils ツールは、一連のドキュメントからHTMLまたはLaTex（およびPDF）を作成できます。
これは、事実上、オプション1とオプション3を組み合わせたものです。
ドキュメントをMarkdownからreStructuredTextに変換しても構わない場合は、 Sphinx を検討してください。マークダウンと同じくらい簡単ですが、はるかに強力です。