readthedocs.orgでMkDocsで外部テーマを使用できますか？

Question

私は、付属のReadtheDocsテーマから私のプロジェクトのBootswatch Unitedテーマに切り替えました。私はpip install mkdocs-bootswatchをこのテーマにして、theme: readthedocsをファイルのtheme: unitedに変更しました。

しかし、このプロジェクトはRead the Docsで正常に構築されますが、ドキュメンテーションは標準のreadthedocsテーマを保持しています。ローカルで（mkdocs serveを使用して）実行すると、Unitedテーマで正しく表示されます。

別のコード行がありますか？私はどこかで調整する必要がありますか？私が追加する必要がある要件ファイル？ ReadtheDocsに外部テーマが正しく表示されるようにするにはどうしたらいいですか？そうでなければ、readthedocs.orgで外部テーマを使用することはできますか？

注：私はMkDocの皆さんに尋ねました。彼らはReadTheDocsの制限だと言いました。何かがあれば、それはReadTheDocs関連の解決策のようです。それ以外の場合は、GitHubページなどに切り替える必要があります。

Answer 1

私はReadtheDocs source codeを見ましたが、実際には自分の設定を上書きして自分のテンプレートを強制しているようです。私が理解しているように、ReadtheDocsに固有のJavaScriptとナビゲーションをページに挿入し、既知のテーマを使用することで、注入が正しく行われているかどうかを確認することができます。つまり、readthedocsのテーマと同じHTMLを使用することはできないが、おそらく異なるCSSを使用してページのルック/スタイリングを変更する技術的な理由はありません。 ReadtheDocsは、これを明示的にサポートしていないようです。

つまり、テンプレートの上書きが発生するのは、if 'theme_dir' not in user_config and self.use_themeです。オーバーライドを避けるために、2つの可能なパスがあります。注入されたものが正しく動作し、慎重に踏み出されるという保証はありません。

1. theme_dirはMkdocs settingです。別個のPythonライブラリとしてMkDocsテーマをインストールするのではなく、テーマファイルをdocs_dirの横のディレクトリにコピーして、theme_dirの設定を指すようにします。 MkDocsがtheme_dirだけを使用するようにtheme: nullを設定してください。

   theme: readthedocsを設定してから、theme_dirを使用すると、組み込みのreadthedocsテーマで提供されたCSSを上書き/置き換える独自のCSSファイルのみを提供できます。これはReadtheDocs注射のほうが敵対的でなく、好きなように見えるはずです。ただし、既存のテーマのHTMLに制限されているため、独自のCSSを作成する必要があります（すでに作成されているテーマは使用しないでください）。

   そのため、themeを任意のテーマに設定し、theme_dirを空のディレクトリに設定することができます。 ReadtheDocsはtheme_dirが設定されているかどうかだけチェックし、ディレクトリに実際に存在するものは気にしません。

   注：私はこれらの提案をテストしておらず、動作するかどうかは確信できません。 YMMV。

   これ以外のところでは、このすべての仕組み（themeとtheme_dirの設定間のやりとり）についてのMkdDocsのドキュメントは現在のところ非常に欠けています。しかし、いくつかの最近のadditionsは、MkDocsの次のバージョン（0.16）がリリースされたときにライブになります。

2. use_themeは、読書帳に固有のように見え、hardcodedは内部的に見えます。私の推測では、これはユーザーによって上書きされないということです。これが提供するオプションがあれば、それが何であるかを判断するためには、コードの詳細な調査が必要となるでしょう。