Ustaw poziomy nagłówków dokumentów automatycznie na podstawie poziomów głębokości folderów (pod (pod (…))), do których należą
Załóżmy, że mam:
foo0.rst
plik w katalogu głównym (source
) mojegosphinx-doc
folderu źródłowego,foo1.rst
plik w podfolderzesubfolder1
zsource
,foo2.rst
plik w podfolderzesubfolder2
zsubfolder1
,
to jest:
$ tree source
source
├── foo0.rst
└── subfolder1
├── foo1.rst
└── subfolder2
└── foo2.rst
wszystkie z tą samą zawartością:
This a title
============
Teraz, jeśli index.rst
zawiera:
Welcome to Test's documentation!
================================
.. toctree::
:maxdepth: 3
:caption: Contents:
foo0
subfolder1/foo1
subfolder1/subfolder2/foo2
make html
daje:
Welcome to Test’s documentation!
Contents:
• This a title
• This a title
• This a title
to znaczy, że wszystkie nagłówki są sekcjami.
Zamiast tego chciałbym otrzymać:
Welcome to Test’s documentation!
Contents:
• This a title
◦ This a title
▪ This a title
to jest nagłówek:
foo0.rst
bycie sekcją,subfolder1/foo1.rst
będąc podsekcją (a nie sekcją),subfolder1/subfolder2/foo2.rst
będąc podsekcją (a nie sekcją).
Moje pytanie brzmi zatem: czy możliwe jest, aby poziomy nagłówków dokumentów należących do folderów (pod (pod (...))) były automatycznie zależne od poziomów głębokości folderów, do których należą?
Odpowiedzi
Styl zastosowany do toctree
wpisów zależy od używanego motywu . CSS motywu zastosuje styl do wpisów, na które Sphinx przetłumaczył <ul>
i <li>
zależał zarówno od ich miejsca w „hierarchii dokumentów”, biorąc pod uwagę sposób, w jaki łączysz łańcuch toctrees
i strukturę sekcji w poszczególnych .rst
plikach.
Na przykład sprawdź elementy HTML generowane przez Sphinx. toctree
Będzie div class="toctree-wrapper compound"
z każdego poziomu odcinków został nazwany <li class="toctree-l1">
potem <li class="toctree-l2">
, etc ...
Jednym ze sposobów osiągnięcia tego, co chcesz, jest otoczenie danego toctree
elementu za pomocą .. class::
dyrektywy (jak pokazano tutaj ) i zastosowanie niestandardowego stylu . Ale miałoby to wpływ na styl innych .rst
plików, które chcesz uwzględnić jako wpisy w tym toctree
.
W każdym razie poniesiesz dodatkową pracę i potencjalnie stracisz automatyzm, jeśli zmienisz swój projekt.
Istnieje również jedno możliwe obejście , używając tej :hidden:
opcji razem z :include:dyrektywą. Jeśli zadeklarujesz ukryty toctree
przed widocznym toctree
w „hierarchii dokumentu” można ustalić położenie wpisu dla Ciebie w hierarchii. Następnie element widoczny toctree
bez :hidden:
opcji będzie renderował .rst
wpisy w pliku jako <li>
element o ustalonej pozycji w hierarchii. (Dokładny przykład można zobaczyć w tym poście ).
Można to zrobić, ale będziesz pracować przeciwko cechom toctree
.
Najpopularniejszym rozwiązaniem jest pisanie .rst
plików i sekcji w zależności od tego, jak chcesz toctree
wyświetlać. (Takie podejście ma wszystkie zalety z jedyną wadą polegającą na ograniczaniu sposobu zapisywania .rst
plików). Jest to prawdopodobnie lepsze rozwiązanie niż próba dostosowania stylów CSS lub stosowanie obejść.
EDYTOWAĆ:
To, co napisałem wcześniej, jest aktualne, ale chyba zbyt ogólne. Podam więc jedno możliwe rozwiązanie tego przykładu. Jeśli chcesz, aby:
Contents:
• This a title (foo0)
◦ This a title (foo1)
▪ This a title (foo2)
Prostą opcją jest użycie łańcucha toctree
s. Możesz ukryć toctree
pozycje, które znajdują się niżej w hierarchii dokumentu, jeśli nie chcesz ich widzieć.
index.rst
.. toctree::
:maxdepth: 3
foo0
i w foo0.rst
.. toctree::
:maxdepth: 3
:hidden:
subfolder1/foo1
i w subfolder1/foo1.rst
.. toctree::
:maxdepth: 3
:hidden:
subfolder1/subfolder2/foo2
Wynik będzie taki, jak podałeś.