Ustaw poziomy nagłówków dokumentów automatycznie na podstawie poziomów głębokości folderów (pod (pod (…))), do których należą

Dec 04 2020

Załóżmy, że mam:

  • foo0.rstplik w katalogu głównym ( source) mojego sphinx-docfolderu źródłowego,
  • foo1.rstplik w podfolderze subfolder1z source,
  • foo2.rstplik w podfolderze subfolder2z subfolder1,

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.rstzawiera:

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

1 bad_coder Dec 04 2020 at 20:37

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 toctreesi strukturę sekcji w poszczególnych .rstplikach.

Na przykład sprawdź elementy HTML generowane przez Sphinx. toctreeBę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 toctreeelementu za pomocą .. class::dyrektywy (jak pokazano tutaj ) i zastosowanie niestandardowego stylu . Ale miałoby to wpływ na styl innych .rstplikó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 toctreeprzed widocznym toctreew „hierarchii dokumentu” można ustalić położenie wpisu dla Ciebie w hierarchii. Następnie element widoczny toctreebez :hidden:opcji będzie renderował .rstwpisy 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 .rstplików i sekcji w zależności od tego, jak chcesz toctreewyświetlać. (Takie podejście ma wszystkie zalety z jedyną wadą polegającą na ograniczaniu sposobu zapisywania .rstplikó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 toctrees. Możesz ukryć toctreepozycje, 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ś.