Jak dołączyć stronę główną do spisu Sphinx?

Question

Powiedzmy mam projekt Sphinx z następujących źródeł:

index.rst 
installation.rst 
templating/ 
    index.rst 
    module.rst 
    fieldtype.rst 

index.rst (strona główna) ma następujący drzewo TOC:

.. toctree:: 
    :titlesonly: 

    installation 
    templating/index 

chcę mój szablon do obejmują pasek boczny zawierający wszystkie 3 strony najwyższego poziomu (strona główna, instalacja, szablon/indeks).

Próbowałem dodanie drugiego, ukrytego drzewa TOC w głównej:

.. toctree:: 
    :hidden: 

    index 

.. toctree:: 
    :titlesonly: 

    installation 
    templating/index 

To rzeczywiście daje mi pożądanego rezultatu, wyjątkiem że czyni next zmienny zestaw do bieżącej strony. Więc ten kod w moim szablonie:

Next up: <a href="{{ next.link }}">{{ next.title }}</a> 

... zawsze wyświetla link strony głównej ze strony głównej. Nie dobrze.

Zawsze starał się zakodować rzeczywistą stronę odnośnik prawo w bocznym w szablonie:

{% set homeClass = 'current' if pagename == 'index' else '' %} 
<ul class="{{ homeClass }}"> 
    <li class="toctree-l1 {{ homeClass }}"><a class="{{ homeClass }} reference internal" href="/index.html">Home</a></li> 
</ul> 
{{ toctree() }} 

To też działa, oprócz tego, że nie chcę, aby wymusić docs być dostępne na webroot serwera WWW - chcę, żeby działały również z systemu plików.

Nie mogę po prostu ustawić adresu URL na "index.html", ponieważ nie zadziała, gdy znajdujesz się w pliku w szablonie /.

Czy brakuje mi czegoś oczywistego? Musi istnieć sposób na przeniesienie strony głównej do spisu treści, bez łamania łączy i dynamicznej ścieżki, która działa w lokalnym systemie plików, nawet z podfolderów.

Answer 1

Okazuje się, że odpowiedź została ukrywanie na widoku na Sfinksa TOC tree page:

specjalną nazwę wejścia self stojaki do dokumentu zawierającego dyrektywę toctree. Przydaje się to, jeśli chcesz wygenerować "mapę witryny" z toctree.

Dodanie self do drzewa spisu treści doskonale poradziło sobie! A jeśli umieścisz go w oddzielnej, ukrytej dyrektywie, nie pojawi się na spisie treści strony głównej:

.. toctree:: 
    :hidden: 

    self 


.. toctree:: 
    :titlesonly: 

    installation 
    templating/index 

Answer 2

Czy istnieje możliwość zmiany nazwy strony głównej roota projektu Sphinx lub alternatywnie strony szablonu/indeksu? Zmienna master_doc umożliwia nazwanie pliku w projekcie, który zawiera dyrektywę root roocree i nie trzeba jej nazywać index.rst ... w naszym projekcie dokumentacji, aby obejść problem podobny do tego, mamy plik template/index.html i nasza strona główna roota jest w rzeczywistości nazywana reference.rst.