6

含まれている ReadtheDocs テーマから、プロジェクトの bootswatch United テーマに切り替えました。私はpip install mkdocs-bootswatchこのテーマを作成し、ファイルに変更theme: readthedocsしました。theme: unitedmkdocs.yml

ただし、プロジェクトは Read the Docs で正常にビルドされますが、ドキュメントは標準の readthedocs テーマを保持します。ローカルで ( を使用してmkdocs serve) 実行すると、United テーマで正しく表示されます。

どこかを調整する必要がある別のコード行はありますか? 追加する必要がある要件ファイルは? 外部テーマを ReadtheDocs に適切に表示するにはどうすればよいですか? または実際、readthedocs.org で外部テーマを使用することもできますか?

注: MkDocs の関係者に尋ねたところ、ReadTheDocs の制限であるとのことでした。そのため、何かすることがあれば、ReadTheDocs 関連の解決策になるようです。そうしないと、GitHub ページなどに切り替える必要があるかもしれません。

4

1 に答える 1

4

ReadtheDocs のソース コードを調べたところ、実際には設定を上書きして独自のテンプレートを強制しているようです。私が理解しているように、彼らは JavaScript と ReadtheDocs に固有のナビゲーションをページに挿入し、既知のテーマを使用することで、挿入が正しく行われることを確認できるため、これを行います。そうは言っても、readthedocs テーマと同じ HTML を使用できない技術的な理由はないはずですが、ページの外観/スタイルを変更するためにおそらく異なる CSS を使用する必要があります。ReadtheDocs がこれを明示的にサポートしていないように見えるだけです。

そうは言っても、テンプレートのオーバーライドのみが発生することに気付きましたif 'theme_dir' not in user_config and self.use_theme。これにより、オーバーライドを回避するための 2 つの可能なパスが得られます。注入されたものが正しく機能するという保証はないので注意してください。

  1. theme_dirはMkdocsの設定です。MkDocs テーマを別の Python ライブラリとしてインストールするのではなく、テーマ ファイルを の隣のディレクトリにコピーしてdocs_dir、theme_dir設定をそこに向けることができます。MkDocstheme: nullのみがtheme_dir.

    おそらく、より積極的なアプローチとして、 を設定し、組み込みの readthedocs テーマによって提供される CSS をオーバーライド/置換する独自の CSS ファイルのみを提供するためにtheme: readthedocs使用することができます。theme_dirこれにより、ReadtheDocs インジェクションに対する敵意が減り、好みの外観になるはずです。ただし、既存のテーマの HTML に制限されており、独自の CSS を作成する必要があるため (既に作成されたテーマを使用しないでください)、これを正しく行うにはさらに多くの作業が必要になる場合があります。

    themeさらに言えば、必要なテーマに設定してtheme_dirから、空のディレクトリを指すことができます。ReadtheDocstheme_dirは設定されていることのみをチェックし、ディレクトリに実際に存在するものは気にしないようです。

    注:これらの提案のいずれもテストしていないため、確実に機能するかどうかはわかりません。YMMV。

    余談ですが、これがどのように機能するか (themeとtheme_dir設定の間の相互作用) に関する MkdDocs のドキュメントは、現在非常に不足しています。ただし、MkDocs の次のバージョン (0.16) がリリースされると、いくつかの最近の追加が有効になります。

  2. use_themereadthedocs に固有であり、内部でハードコーディングされているようです。私の推測では、これはユーザーがオーバーライドすることはできません。これによりどのようなオプションが提供されるかを判断するには、コードをより深く調査する必要があります。

于 2016-06-22T14:00:57.547 に答える