基本 (1) - Sphinxを使用する前に -

特徴

1. マークアップ言語 ：

   • ReStructuredText(ReST) と呼ばれる シンプル で 読み易い マークアップ言語で文書を記述．

2. 同一ファイルから 多種の出力フォーマットに対応 ：

   • HTML、PDF、ePub、テキスト、様々なドキュメントが同一ファイルから生成可能．

   • 異なるプラットフォームやメディアに適したドキュメントを一括で作成可能．

3. 容易なコード統合と自動生成によりドキュメント保守が容易 ：

   • コードのドキュメンテーションに適しており、 種々の言語のハイライトやリンクが生成でき、目次、索引、クロスリファレンスなどは自動的に生成できる．

4. カスタマイズ性とコミュニティ・エコシステム ：

   • Sphinxは、多くの 設定オプションと拡張機能を提供 し、プロジェクトのニーズに合わせてカスタマイズ可能．多くのオープンソースプロジェクトで採用され、コミュニティがサポート．

新規の使用は非推奨な件

オワコンな件

• chatGPTにオワコンかと尋ねたら、 "オーワコン(??)じゃない" と返ってきた．

  • が、しかし、正直、Sphinxプロジェクトは、実際ほぼ出オチで、 オワコンと化してるのが現状 ．

  • 整備や開発があまり進んでない．枯れたといえるほど整備もされてない．

  • python公式ともの好き以外、誰が使ってるのか？という印象．

それでも使用するのは

• だが、HTML書くより、断然マシ．GUIやHPビルダを使用しなくて良い．

• 学習のサンクコスト ( Sunk Cost )

• コード書きとの親和性は高く、便利な部分は少ないが、あるにはある．

  • ( 当然、このHTMLもSphinxで書いてる )

• 「新規でSphinxをはじめよう」と思う人は、 素直にReSTよりMarkdownなどをやったほうが良い と思う．

• 本文献は、個人的備忘録、と 一部の "もの好き" のためか．