ドキュメントの見出しレベルを、ドキュメントが属する（sub（sub（…）））フォルダーの深さのレベルに自動的に依存させる

Dec 04 2020

私が持っているとしましょう：

ソースフォルダのfoo0.rstルート（source）にあるファイルsphinx-doc、
foo1.rstサブフォルダ内のファイルsubfolder1のsource、
foo2.rstサブフォルダ内のファイルsubfolder2のsubfolder1、

あれは：

$ tree source
source
├── foo0.rst
└── subfolder1
    ├── foo1.rst
    └── subfolder2
        └── foo2.rst

すべて同じ内容：

This a title
============

ここで、がindex.rst含まれている場合：

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html 与える：

Welcome to Test’s documentation!

Contents:

    • This a title
    • This a title
    • This a title

つまり、すべての見出しはセクションです。

代わりに取得したいのは次のとおりです。

Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

それは次の見出しです：

foo0.rst セクションであること、
subfolder1/foo1.rst サブセクション（セクションではない）であり、
subfolder1/subfolder2/foo2.rst サブサブセクションである（セクションではない）。

したがって、私の質問は、（sub（sub（...）））フォルダーに属するドキュメントの見出しレベルを、それらが属するフォルダーの深さのレベルに自動的に依存させることは可能ですか？

回答

1 bad_coder Dec 04 2020 at 20:37

toctree エントリに適用されるスタイルは、使用しているテーマによって異なります。テーマのCSSは、スフィンクスがに翻訳することをエントリにスタイルを適用する<ul>と、<li>内のその場所の両方に応じて、「ドキュメント階層」あなたがチェーンどのように与えられtoctrees、どのようにあなたの部分の構造の個々の中.rstのファイルが編成されています。

たとえば、Sphinxが生成するHTML要素を調べます。toctreeなりますdiv class="toctree-wrapper compound"と命名されたセクションの各レベルで<li class="toctree-l1">、その後<li class="toctree-l2">、等...

目的を達成する1つの方法は、（ここに示すように）ディレクティブtoctreeを使用して特定の.. class::サイズを囲み、カスタムスタイルを適用することです。ただし、その場合、エントリとして含める他のファイルのスタイルに影響します。.rsttoctree

いずれにせよ、プロジェクトをリファクタリングすると、余分な作業が発生し、自動化が失われる可能性があります。

オプションをディレクティブと一緒に使用することで、1つの可能な回避策もあり:hidden:ます:include:。表示のtoctree前に非表示を宣言するとtoctree、「ドキュメント階層」によって階層内のエントリの位置を修正できます。その後、オプションtoctreeなしで表示さ:hidden:れると、.rstファイルエントリ<li>が階層内の固定位置を持つ要素としてレンダリングされます。（完全な例はこの投稿で見ることができます）。

それは可能ですが、の特性に逆らって作業しますtoctree。

一般的な解決策は.rst、toctree表示方法に応じてファイルとセクションを書き込むことです。（このアプローチにはすべての利点がありますが、.rstファイルの書き込み方法に制限を設けるという唯一の欠点があります）。CSSスタイルを適応させたり、回避策を使用したりするよりも、おそらくこれが望ましい解決策です。

編集：

私が以前に書いたことは有効ですが、おそらく一般的すぎます。そこで、この例の1つの可能な解決策を示します。以下が必要な場合：

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

簡単なオプションは、toctreesのチェーンを使用することです。表示しtoctreeたくない場合は、ドキュメント階層の下位にあるを非表示にすることができます。