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

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

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

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


django pagination restructuredtext
person eaman    schedule 24.08.2010    source источник

Ответы (1)


arrow_upward
1
arrow_downward

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

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

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

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

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

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

person S.Lott    schedule 24.08.2010
comment
Спасибо, я обдумывал Вариант 1, который, похоже, разделяет другую документацию в других проектах (обычно с использованием Sphinx, который я также использовал). Вариант 2. выглядит интересно, но я бы хотел (ищу способ): - хранить мои документы в формате *.rst, чтобы я мог управлять ими с помощью Git и генерировать выходные данные по мере необходимости - хранить весь процесс в Django без необходимости проходить через Sphinx Choice 1. выглядит просто и легко реализовать: я посмотрю на свою библиотеку и посмотрю, как мои документы адаптируются к ней. Спасибо за совет. - person eaman; 24.08.2010