Machen Sie die Überschriftenebenen von Dokumenten automatisch abhängig von den Tiefenebenen der Ordner (sub (sub (…))), zu denen sie gehören

Dec 04 2020

Angenommen, ich habe:

  • eine foo0.rstDatei im Stammverzeichnis ( source) meines sphinx-docQuellordners,
  • eine foo1.rstDatei in einem Unterordner subfolder1von source,
  • eine foo2.rstDatei in einem Unterordner subfolder2von subfolder1,

das ist:

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

alle mit dem gleichen Inhalt:

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

Nun, wenn das index.rstenthält:

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

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

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html gibt:

Welcome to Test’s documentation!

Contents:

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

Das heißt, alle Überschriften sind Abschnitte.

Was ich stattdessen gerne bekommen würde, ist folgendes:

Welcome to Test’s documentation!

Contents:

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

das ist die Überschrift von:

  • foo0.rst ein Abschnitt sein,
  • subfolder1/foo1.rst ein Unterabschnitt (und kein Abschnitt) sein,
  • subfolder1/subfolder2/foo2.rst ein Unterabschnitt sein (und kein Abschnitt).

Meine Frage lautet daher: Ist es möglich, die Überschriftenebenen von Dokumenten, die zu (Unter- (Unter- (...))) Ordnern gehören, automatisch von den Tiefenebenen der Ordner abhängig zu machen, zu denen sie gehören?

Antworten

1 bad_coder Dec 04 2020 at 20:37

Der auf die toctree Einträge angewendete Stil hängt vom verwendeten Thema ab . Das CSS des Themas wendet einen Stil auf die Einträge an, in die Sphinx übersetzt hat, <ul>und <li>hängt von ihrem Platz innerhalb der "Dokumenthierarchie" ab , je nachdem , wie Sie die Abschnittskette verkettentoctrees und wie Ihre Abschnittsstruktur in den einzelnen .rstDateien organisiert ist.

Überprüfen Sie beispielsweise die HTML-Elemente, die Sphinx generiert. Das toctreewird ein div class="toctree-wrapper compound"mit jeder Ebene von Abschnitten sein, die <li class="toctree-l1">dann benannt werden <li class="toctree-l2">, etc ...

Eine Möglichkeit, das zu erreichen, was Sie möchten, besteht darin, eine bestimmte Anweisung (wie hier gezeigt ) toctreemit einer .. class::Direktive zu umgeben und einen benutzerdefinierten Stil anzuwenden . Dies würde sich dann jedoch auf den Stil aller anderen Dateien auswirken, die Sie als Einträge in diese Dateien aufnehmen möchten ..rsttoctree

In jedem Fall entstehen Ihnen zusätzliche Arbeit und möglicherweise lockerer Automatismus, wenn Sie Ihr Projekt umgestalten.

Es gibt auch eine mögliche Problemumgehung , indem die :hidden:Option zusammen mit der :include:Direktive verwendet wird. Wenn Sie ein verstecktes toctreevor einem sichtbaren deklarieren, kann toctreedie "Dokumenthierarchie" die Position eines Eintrags für Sie in der Hierarchie festlegen. Danach rendert das Sichtbare toctreeohne die :hidden:Option .rstDateieinträge als ein <li>Element mit einer festen Position in der Hierarchie. (Ein ausführliches Beispiel finden Sie in diesem Beitrag ).

Es kann getan werden, aber Sie werden gegen die Eigenschaften der arbeiten toctree.

Die gängige Lösung besteht darin, Ihre .rstDateien und Abschnitte zu schreiben, je nachdem, wie sie toctreeangezeigt werden sollen. (Dieser Ansatz bietet alle Vorteile mit dem einzigen Nachteil, dass das Schreiben der .rstDateien eingeschränkt wird.) Dies ist wahrscheinlich die bevorzugte Lösung, anstatt zu versuchen, die CSS-Stile anzupassen oder Problemumgehungen zu verwenden.


BEARBEITEN:

Was ich vorher geschrieben habe, ist gültig, aber wahrscheinlich zu allgemein. Also werde ich eine mögliche Lösung für das Beispiel geben. Wenn Sie Folgendes möchten:

Contents:

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

Eine einfache Option ist die Verwendung einer Kette von toctrees. Sie können die toctreein der Dokumenthierarchie niedrigeren Werte ausblenden , wenn Sie sie nicht sehen möchten.

index.rst

.. toctree::
   :maxdepth: 3

   foo0

und in foo0.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

und in subfolder1/foo1.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

Das Ergebnis entspricht Ihren Angaben.