オープンソースプロジェクトのドキュメントを管理するには？[閉まっている]

私は成長しているオープンソースプロジェクトの作成者です。現在、ドキュメントを管理する最良の方法を見つけようとしていらいらしています。私が検討したオプションは次のとおりです。

• HTMLウェブサイト
• Github Wiki
• Githubでホストされるマークダウンファイル
• Github README.mdにすべてのドキュメントを配置する

ドキュメントは既にMarkdownで書かれていますが、どのようにそれを利用可能にしたいのかわかりません。ソースを分岐およびタグ付けできるのと同じように、ドキュメントを分岐およびタグ付けできるので、Gitに本当に惹かれています。

Markdownライブラリを使用して、MarkdownをHTMLに変換し、スタイル付きのWebサイトに表示できます。変更があった場合はいつでもWebサイトに変更をアップロードする必要があり、ドキュメントのさまざまな「タグ」をすべて管理することは困難です。

Github Wiki（私の知る限り）は、あなたがいるブランチによって変わりません。そのため、Github Wikiフォームには常に「マスター」バージョンのドキュメントしかありませんでした。

すべてをGithubのREADMEに入れておくと、とてもきれいになります。分岐とタグ付けはできますが、使用するのは少し面倒で、簡単なナビゲーションには向いていません。

素晴らしいソリューションがありませんか？他にどんなオプションがありますか？

私が言うことの1つは、ドキュメントをソースコードファイルに（必要なマークアップを使用して）配置し、これらから自動的に生成されるドキュメントでなければならないということです。
少なくともあなたのサイトでは、ユーザーが特定のドキュメントツールを必要としないように、ソースパッケージの一部としてドキュメントのフォーマットされたダウンロードを生成できます。

他の誰かが関数を修正/追加し、同じファイル内で隣接するマークアップドキュメントを編集/追加する可能性は低いかもしれませんが、同じことを行うために別のドキュメントリポジトリで完全に異なるファイルを見つける可能性はわずかですゼロ未満。

必要に応じて、大きなテキストブロックを含むtutorial.hをいつでも使用できますが、ソースの一部として扱います

プロジェクトがライブラリの場合、コード内のコメントからAPI構文を文書化するjavadocスタイルのドキュメントに勝るものはありません。

チュートリアル、使用例などのドキュメントについては、Wiki形式を使用することを強くお勧めします。私が見た他のプロジェクトには、ブランチごとに別々のページがあります。新しいブランチを開始するときは、新しいページに変更されていないものをコピーして、そこから更新します。

ウィキを推奨する私の理由は逸話的ですが、個人的な経験からです。私はドキュメントの更新をオープンソースプロジェクトに何度か寄稿しましたが、それらはすべてウィキにあります。何かを理解しようとしてドキュメントが誤解を招いたり役に立たなかったりする場合は、ドキュメントを読んでいる間にウィキを更新します。少なくとも、1年か2年後に自分で調べ直さなければならない可能性があることを知っているからです。

wikiがない場合、ドキュメントの生成方法、保存場所、ソース管理から最新情報を取得する方法、編集方法、実際の編集方法、およびメーリングリストをナビゲートして、パッチを受け入れます。

ドキュメントをきめ細かく制御したい場合は、ほとんどの場合、あなたにとって最も快適なものを使用してください。更新するのはほとんどあなただけだからです。コミュニティへの参加を促進したい場合は、Wikiを使用してください。

ソースでホストされているマークダウンファイルは非常にうまく機能します。

たとえば、RSTベースのdocutilsツールは、1組のドキュメントからHTMLまたはLaTex（およびPDF）を作成できます。

これは、事実上、オプション1とオプション3を組み合わせたものです。

ドキュメントをMarkdownからreStructuredTextに変換してもかまわない場合は、Sphinxを検討してください 。マークダウンと同じくらい簡単ですが、はるかに強力です。