Вывод html нескольких страниц из документа .rst в Django

Question

Я пишу приложение Django для обслуживания некоторой документации, написанной в RestructuredText. У меня есть много документов, написанных на * .rst, каждый из них довольно длинный, со множеством разделов, подразделов и т. Д.

Отображение всего документа на одной странице не является проблемой при использовании фильтров Django, но я бы предпочел иметь только указатель темы на первой странице, а ссылки на URL, где я могу отобразить один раздел / подраздел понадобится ссылка «предыдущая | вверх | домой | следующая», я думаю ...). Аналогично «выводу нескольких HTML-страниц», как при преобразовании документации / XML в HTML.

Может ли кто-нибудь указать мне направление построения дерева документа * .rst документа, проанализировать его отдельный раздел или предложить более умный способ получить аналогичный результат?

Answer 1

Вариант 1. Включите URL-ссылки на другие части документа.

Вы пишете index.rst, part1.rst, part2.rst и т. Д. И ваш index.rst содержит ссылки на другие части. Это почти не требует работы, кроме тщательного планирования, чтобы убедиться, что ваши ссылки RST HTML верны.

Там нет "разбора". Вы просто разбиваете свой документ на разделы. Вручную.

[Это кажется таким очевидным, я боюсь упоминать об этом.]

Вариант 2. Используйте Сфинкс . Он очень хорошо управляет оглавлением и связями между документами.

Однако расширения Sphinx для RST не обрабатываются непосредственно Django, поэтому вам нужно сохранить выходные данные Sphinx, а затем отобразить их в Django. Мы используем JSON HTML Builder (http://sphinx.pocoo.org/builders.html?highlight=json#sphinx.builders.html.JSONHTMLBuilder) вывод из Sphinx. Затем мы визуализируем эти документы с помощью шаблона.