Machen Sie die Überschriftenebenen von Dokumenten automatisch abhängig von den Tiefenebenen der Ordner (sub (sub (…))), zu denen sie gehören
Angenommen, ich habe:
- eine
foo0.rst
Datei im Stammverzeichnis (source
) meinessphinx-doc
Quellordners, - eine
foo1.rst
Datei in einem Unterordnersubfolder1
vonsource
, - eine
foo2.rst
Datei in einem Unterordnersubfolder2
vonsubfolder1
,
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.rst
enthä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
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 .rst
Dateien organisiert ist.
Überprüfen Sie beispielsweise die HTML-Elemente, die Sphinx generiert. Das toctree
wird 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 ) toctree
mit 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 ..rst
toctree
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 toctree
vor einem sichtbaren deklarieren, kann toctree
die "Dokumenthierarchie" die Position eines Eintrags für Sie in der Hierarchie festlegen. Danach rendert das Sichtbare toctree
ohne die :hidden:
Option .rst
Dateieinträ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 .rst
Dateien und Abschnitte zu schreiben, je nachdem, wie sie toctree
angezeigt werden sollen. (Dieser Ansatz bietet alle Vorteile mit dem einzigen Nachteil, dass das Schreiben der .rst
Dateien 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 toctree
s. Sie können die toctree
in 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.