Sortie html de plusieurs pages depuis un document .rst dans Django

Question

J'écris une application Django pour servir une documentation écrite en RestructuredText. J'ai beaucoup de documents écrits en * .rst, chacun d'eux est assez long avec beaucoup de section, sous-section et ainsi de suite. Afficher l'ensemble du document sur une seule page n'est pas un problème avec les filtres Django, mais je préfère avoir l'index des rubriques sur une première page, qui renvoie à une URL où je peux afficher une seule section/sous-section (qui aura besoin d'un lien «previous | up | home | next» je suppose ...). D'une manière similaire à une «sortie de page HTML multiple» comme dans une conversion docbook/XML en HTML.

Est-ce que quelqu'un peut me diriger dans une certaine direction pour construire une arborescence de documents d'un document * .rst, en analyser une seule section ou suggérer une manière intelligente d'obtenir un résultat similaire?

Answer 1

Choix 1. Inclure les liens URL vers les autres parties du document.

Vous écrivez un index.rst, un part1.rst, un part2.rst, etc. Et votre index.rst contient des liens vers les autres parties. Cela ne nécessite presque aucun travail, sauf une planification minutieuse pour vous assurer que vos liens HTML RST sont corrects.

Il n'y a pas d '"analyse". Vous venez de diviser votre document en sections. Manuellement.

[Cela semble tellement évident, je crains de le mentionner.]

Choix 2. Utilisez Sphinx. Il gère très bien la table des matières et les connexions inter-documents.

Cependant, les extensions Sphinx à la TVD ne sont pas traitées directement par Django, vous aurez besoin d'enregistrer la sortie Sphinx, puis afficher que Django. Nous utilisons la sortie JSON HTML Builder (http://sphinx.pocoo.org/builders.html?highlight=json#sphinx.builders.html.JSONHTMLBuilder) de Sphinx. Ensuite, nous rendons ces documents à travers un modèle.