Estructura dels documents amb Sphinx

Quan encetem un projecte de documentació amb Sphinx només seguint les indicacions bàsiques veurem que cada fitxer es converteix en un capítol. Dins d'aquest capítol, amb la formatació RST d'encapçalaments,  podem crear seccions i subseccions. Però, com podem incloure subdocuments dins d'aquesta estructura?. En altres paraules, com dibuixem l'arbre de continguts del document? Com aconseguim una pàgina inicial com aquesta?:

La clau resideix a la directiva toctree (literalment l'arbre de la taula de continguts). Una directiva a RST i a Sphinx és un bloc genèric de marcatge explícit i serveix per indicar quan introduir una imatge, un avís, blocs HTML i altres elements al cos del document. Per exemple, per fer aparèixer una imatge en un punt del document RST escrivim la directiva image:

.. image:: foto.jpg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: text alternatiu
   :align: right

En concret la directiva toctree fa que en aquell punt del document hi aparegui una taula de continguts a base de documents relacionats amb ell. Per exemple, la pàgina índex de l'exemple té una directiva toctree que inclou 3 documents principals o Capítols:

.. toctree::
   :maxdepth: 3

   #:numbered:

   #:caption: Taula de continguts

   introduccio
   cos
   conclusio

on maxdepth defineix la profunditat de la Taula de continguts (fins al nivell 3, encara que usualment és fins a 2).
numbred numerarà els capítols a la Taula
caption és el títol de la Taula, per exemple "Aquí hi trobaràs..."

Si volem que d'un capítol, com ara Cos, pengin diferents documents o subcapítols, només cal que hi tornem a posar una directiva toctree. Per exemple al document que genera el capítol Cos hi ha la directiva:

.. toctree::
   :maxdepth: 2

   cos1
   cos2
   cos3

I al document cos3 s'hi ha inclòs la directiva:

.. toctree::
   :maxdepth: 2

   cos31
   cos32

D'aquesta manera es poden anar niuant uns documents dins dels altres i construir, finalment, l'arbre de continguts.

PS:
1.- El tema d'Sphinx utilitzat a l'exemple, ITCase, es pot descarregar de https://pypi.python.org/pypi/itcase-sphinx-theme/0.2.0

2.- Per catalanitzar-ne els peus i altres detalls només cal entrar al seu directori del nostre ordinador: /home/joan/.local/lib/python2.7/site-packages/itcase_sphinx_theme/itcase

3.-+info: Restructured Text (reST) and Sphinx CheatSheet