Come posso includere la homepage nel TOC Sphinx?

Question

Diciamo che ho un progetto Sfinge con le seguenti fonti:

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

index.rst (homepage) ha la seguente albero TOC:

.. toctree:: 
    :titlesonly: 

    installation 
    templating/index 

voglio che il mio modello per includere un barra laterale che elenca tutte e 3 le pagine di primo livello (homepage, installazione, templatura/indice).

Ho provato ad aggiungere un secondo, albero TOC nascosto nella home page:

.. toctree:: 
    :hidden: 

    index 

.. toctree:: 
    :titlesonly: 

    installation 
    templating/index 

Che in realtà mi dà il risultato desiderato, ad eccezione che rende il next variabile impostata alla pagina corrente. Quindi questo codice nel mio modello:

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

... emette sempre il collegamento della homepage dalla home page. Non buono.

io ho sempre cercato di codificare il link home page effettiva a destra nella barra laterale del modello:

{% 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() }} 

che funziona anche, se non che io non voglio forzare la documentazione a cui accedere in webroot di un server web - Voglio che anche loro lavorino dal file system.

Non riesco a impostare semplicemente l'URL su "index.html" perché non funzionerà quando ci si trova in un file all'interno di template /.

Mi manca qualcosa di ovvio? Ci deve essere un modo per ottenere la homepage nel sommario, senza interrompere i collegamenti next e con un percorso dinamico che funziona su un file system locale, anche da sottocartelle.

Answer 1

Attiva la risposta era nascosto in bella vista su Sphinx di TOC tree page:

Il nome della voce speciale self sta per il documento che contiene la direttiva toctree. Questo è utile se vuoi generare una "sitemap" dal toctree.

L'aggiunta di self all'albero TOC ha fatto il trucco perfettamente! E se lo si inserisce in una, direttiva toctree nascosta separata, non verrà mostrata sul tavolo del homepage dei contenuti o:

.. toctree:: 
    :hidden: 

    self 


.. toctree:: 
    :titlesonly: 

    installation 
    templating/index 

Answer 2

E 'possibile rinominare la pagina Toctree radice del progetto Sphinx o, in alternativa, la pagina di modello/indice? La variabile master_doc consente di denominare il file nel progetto che contiene la direttiva toctree radice e non deve essere chiamato index.rst ... nel nostro progetto di documentazione per aggirare un problema molto simile, abbiamo un file template/index.html e la nostra pagina toctree di root è in realtà chiamata reference.rst.