Membuat tingkat judul dokumen secara otomatis bergantung pada tingkat kedalaman folder (sub (sub (...))) tempat mereka berada

Question

Misalkan saya memiliki:

• sebuah foo0.rstfile pada root ( source) saya sphinx-docfolder sumber,
• sebuah foo1.rstfile dalam subfolder subfolder1dari source,
• sebuah foo2.rstfile dalam subfolder subfolder2dari subfolder1,

itu adalah:

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

semua dengan konten yang sama:

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

Sekarang, jika index.rstberisi:

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

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

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html memberikan:

Welcome to Test’s documentation!

Contents:

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

itu semua judul adalah bagian.

Yang ingin saya dapatkan adalah sebagai berikut:

Welcome to Test’s documentation!

Contents:

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

itu adalah tajuk dari:

• foo0.rst menjadi bagian,
• subfolder1/foo1.rst menjadi subbagian (dan bukan bagian),
• subfolder1/subfolder2/foo2.rst menjadi sub-sub bagian (dan bukan bagian).

Oleh karena itu, pertanyaan saya adalah: apakah mungkin membuat level heading dokumen yang termasuk dalam folder (sub (sub (...))) secara otomatis bergantung pada level kedalaman folder tempat mereka berada?

Answer 1

Gaya yang diterapkan ke toctree entri tergantung pada tema yang Anda gunakan. CSS tema akan menerapkan gaya ke entri yang diterjemahkan Sphinx <ul>dan <li>bergantung pada tempatnya di dalam "hierarki dokumen" mengingat cara Anda merangkai toctreesdan bagaimana struktur bagian Anda di .rstfile individual diatur.

Misalnya, periksa elemen HTML yang dihasilkan Sphinx. Ini toctreeakan menjadi a div class="toctree-wrapper compound"dengan setiap tingkat bagian dinamai <li class="toctree-l1">kemudian <li class="toctree-l2">, dll ...

Salah satu cara untuk mencapai apa yang Anda inginkan akan mengelilingi yang diberikan toctreemenggunakan .. class::arahan (seperti yang ditunjukkan di sini ) dan menerapkan gaya khusus . Tapi itu kemudian akan memengaruhi gaya .rstfile lain yang ingin Anda sertakan sebagai entri di dalamnya toctree.

Bagaimanapun, Anda akan dikenai pekerjaan ekstra dan kemungkinan otomatisme lepas jika Anda merefaktor ulang proyek Anda.

Ada juga satu solusi yang mungkin , menggunakan :hidden:opsi bersama dengan :include:arahan. Jika Anda menyatakan tersembunyi toctreesebelum terlihat toctreepada "hirarki dokumen" dapat memperbaiki posisi entri untuk Anda dalam hirarki. Setelah itu, tampilan toctreetanpa :hidden:opsi akan membuat .rstentri file sebagai <li>elemen yang memiliki posisi tetap dalam hierarki. (Contoh lengkapnya bisa dilihat di postingan ini ).

Ini bisa dilakukan, tetapi Anda akan bekerja melawan karakteristik file toctree.

Solusi umum adalah menulis .rstfile dan bagian Anda tergantung pada bagaimana Anda ingin toctreemenampilkannya. (Pendekatan ini memiliki semua keuntungan dengan satu-satunya kelemahan dari menempatkan batasan pada cara Anda menulis .rstfile). Ini mungkin solusi yang lebih disukai daripada mencoba menyesuaikan gaya CSS atau menggunakan solusi.

---

EDIT:

Apa yang saya tulis sebelumnya valid, tetapi mungkin terlalu umum. Jadi saya akan memberikan satu solusi yang mungkin untuk contoh tersebut. Jika Anda menginginkan yang berikut ini:

Contents:

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

Opsi sederhana menggunakan rantai toctrees. Anda dapat menyembunyikan toctreeyang lebih rendah dalam hierarki dokumen jika Anda tidak ingin melihatnya.

index.rst

.. toctree::
   :maxdepth: 3

   foo0

dan masuk foo0.rst

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

   subfolder1/foo1

dan masuk subfolder1/foo1.rst

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

   subfolder1/subfolder2/foo2

Hasilnya akan seperti yang Anda tentukan.