문서가 속한 (sub (sub (…))) 폴더의 깊이 수준에 따라 문서의 제목 수준이 자동으로 종속되도록합니다.

Dec 04 2020

내가 가지고 있다고 가정합니다.

  • 내 소스 폴더 foo0.rst의 루트 ( source)에 있는 파일 sphinx-doc,
  • foo1.rst하위 폴더 subfolder1에 있는 파일 source,
  • foo2.rst하위 폴더 subfolder2에 있는 파일 subfolder1,

그건:

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

모두 동일한 내용 :

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

이제 다음이 index.rst포함 된 경우 :

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

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

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html 제공합니다 :

Welcome to Test’s documentation!

Contents:

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

그것은 모든 제목이 섹션이라는 것입니다.

대신 얻고 싶은 것은 다음과 같습니다.

Welcome to Test’s documentation!

Contents:

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

그 제목은 :

  • foo0.rst 섹션이되고,
  • subfolder1/foo1.rst 섹션이 아닌 하위 섹션
  • subfolder1/subfolder2/foo2.rst 섹션이 아닌 하위 하위 섹션입니다.

따라서 내 질문은 : (sub (sub (...))) 폴더에 속하는 문서의 제목 수준이 속한 폴더의 깊이 수준에 자동으로 의존하도록 만들 수 있습니까?

답변

1 bad_coder Dec 04 2020 at 20:37

toctree 항목에 적용되는 스타일 은 사용 중인 테마에 따라 다릅니다 . 테마의 CSS는 스핑크스로 번역하는 항목에 스타일을 적용 <ul>하고 <li>내에서 자신의 자리에 모두 따라 "문서 계층" 당신은 체인 방법을 제공 toctrees하고 방법 섹션 구조 각각의 .rst파일이 구성되어있다.

예를 들어 Sphinx가 생성하는 HTML 요소를 검사합니다. 는 toctree될 것 div class="toctree-wrapper compound"섹션의 각 수준이되는 이름과 <li class="toctree-l1">다음 <li class="toctree-l2">등 ...

원하는 것을 달성하는 한 가지 방법은 ( 여기에toctree 표시된대로) .. class::지시문을 사용하여 주어진 주위를 둘러싸고 사용자 정의 스타일을 적용하는 것 입니다 . 그러나 그것은 항목으로 포함하려는 다른 파일 의 스타일에 영향을 미칩니다 ..rsttoctree

어쨌든 프로젝트를 리팩토링하면 추가 작업이 발생하고 잠재적으로 자동 기능이 느슨해집니다.

또한 지시문 과 함께 옵션을 사용하는 한 가지 가능한 해결 방법 이 있습니다 . 표시하기 전에 숨김을 선언 하면 "문서 계층" 이 계층에서 항목의 위치를 ​​수정할 수 있습니다. 나중에 옵션이 없는 표시 는 계층에서 고정 된 위치를 갖는 요소 로 파일 항목을 렌더링 합니다 . ( 이 게시물에서 철저한 예를 볼 수 있습니다 ).:hidden::include:toctreetoctreetoctree:hidden:.rst<li>

할 수는 있지만 toctree.

널리 사용되는 솔루션은 표시 .rst하려는 방식에 따라 파일과 섹션을 작성 하는 것 toctree입니다. (이 접근법은 .rst파일 작성 방법에 제한을 두는 유일한 단점이있는 모든 장점을 가지고 있습니다.) CSS 스타일을 조정하거나 해결 방법을 사용하는 것보다 선호되는 솔루션 일 것입니다.


편집하다:

이전에 쓴 내용은 유효하지만 너무 일반적 일 수 있습니다. 그래서 나는 예제에 대한 하나의 가능한 해결책을 제공 할 것입니다. 다음을 원하는 경우 :

Contents:

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

간단한 옵션은 toctrees 체인을 사용하는 것입니다 . toctree문서 계층 구조에서 더 낮은의을 보지 않으려면 숨길 수 있습니다 .

index.rst

.. toctree::
   :maxdepth: 3

   foo0

그리고 foo0.rst

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

   subfolder1/foo1

그리고 subfolder1/foo1.rst

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

   subfolder1/subfolder2/foo2

결과는 지정한대로 표시됩니다.