Ignora il modello di pagina html per un documento sfinge specifico

Question

Sto implementando una documentazione utilizzando Sfinge (https://github.com/fridge-project/dbal-docs) & desidera eseguire l'override della pagina html di un documento specifico. Il mio interesse è quello di scavalcare tutti gli indici di directory per mostrare non solo un semplice ul.

Ho letto la documentazione di Sphinx ma non trovo qualcosa di interessante sul mio problema ... Qualcuno conosce una soluzione?

Answer 1

Per la cronaca, questa soluzione è molto più un hack che una soluzione, ma per ora, non mi trovare qualcosa di meglio ...

In primo luogo, di tutto ciò che serve per capire la mia soluzione è basata sulla tematizzazione. Nel tuo documento, usi un tema (quello predefinito o uno personalizzato), ma in ogni caso, usi un tema. Questo tema è diviso in diverse parti (pagina, toc, ...) che possono essere sovrascritte individualmente. Questa sostituzione può essere eseguita a diversi livelli: il tema stesso o nella directory del modello personalizzato del progetto (per impostazione predefinita _templates) (configurabile nello conf.py).

La mia soluzione alternativa è di ignorare il modello page.html nella directory _templates che rappresenta tutte le pagine della documentazione. In questo modello, si ha accesso allo pagename (relativo al percorso doc di ciascun file). Sapendo questo, è possibile eseguire alcuni controlli condizionali in questo modello per rilevare se si tratta di un file che si desidera sovrascrivere & quindi sostituirlo. Se non si tratta di un file che devono essere ignorato, semplicemente ripiego sul comportamento di default:

{% extends "layout.html" %} 
{% block body %} 
    {% if pagename == 'index' %} 
     {% include 'custom/index.html' %} 
    {% else %} 
     {{ body }} 
    {% endif %} 
{% endblock %} 

Come spiegare, suona davvero come un hack ...

Answer 2

Uno dovrebbe essere in grado di utilizzare una variabile per definire il modello da cui estendersi. http://jinja.pocoo.org/docs/2.10/templates/#template-objects

In questo modo potrebbe essere meno di un 'trucco'. E hai il pieno controllo sull'output generato (non solo sul blocco body).

layout.html:
{% extends meta.page_template|default('basic/page.html') %}

E nel tuo index.rst si utilizza poi a livello di pagina-meta-dati: http://www.sphinx-doc.org/en/stable/markup/misc.html#file-wide-metadata

index.rst:
:page_template: custom/index.html <your normal index.rst content>