packages/docutils/rstgen

Исходный код Изменить

Этот модуль реализует генератор HTML/LaTeX из reStructuredText (см. http://docutils.sourceforge.net/rst.html для информации об этом синтаксисе разметки) и используется инструментами документирования компилятора (инструментами docgen).

Вы можете сгенерировать HTML-вывод с помощью удобной процедуры rstToHtml, которая, получив на вход строку с разметкой rst, возвращает строку с сгенерированным HTML. Конечный вывод предполагается встраивать в ваш собственный документ, поэтому он не будет содержать стандартных <header> или <body> частей.

Вы также можете создать RstGenerator структуру и заполнить её другими методами нижнего уровня, чтобы в конечном итоге собрать полные документы. Это требует многих опций и настроек, но вы не ограничены фрагментами и можете также генерировать документы LaTeX.

Файлы конфигурации Docutils не поддерживаются. Вместо этого генерацию HTML можно настроить, отредактировав файл config/nimdoc.cfg.

Существуют стилистические различия в том, как этот модуль отображает некоторые элементы, по сравнению с оригинальным Python Docutils:

Обратные ссылки на содержание (TOC) в заголовках разделов не генерируются. В HTML каждый раздел также является ссылкой, которая указывает на сам раздел: это сделано для того, чтобы пользователь смог скопировать ссылку в буфер обмена.
То же самое относится к ссылкам сносок/цитат: они указывают на себя. Обратные ссылки не генерируются, так как найти все ссылки на сноску можно, просто найдя [footnoteName].

Импорты

strutils, os, hashes, strtabs, tables, sequtils, algorithm, parseutils, strbasics, rstast, rst, rstidx, highlite, since

Типы

EscapeMode = enum
  emText, emOption, emUrl

Исходный код Изменить

IndexedDocs = Table[IndexEntry, seq[IndexEntry]]

Содержит последовательности индексов для типов документов.

Ключ — это фиктивный элемент IndexEntry, который будет содержать заголовок документа в поле keyword и link будет содержать имя html-файла для документа. linkTitle и linkDesc будут пусты.

Значение, индексируемое этим IndexEntry, — это последовательность с реальными элементами индекса, найденными в файле .idx.

Исходный код Изменить

MetaEnum = enum
  metaNone, metaTitleRaw, metaTitle, metaSubtitle, metaAuthor, metaVersion

Исходный код Изменить

OutputTarget = enum
  outHtml, outLatex

какой тип документа генерировать Исходный код Изменить

RstGenerator = object of RootObj
  target*: OutputTarget
  config*: StringTableRef
  splitAfter*: int
  listingCounter*: int
  tocPart*: seq[PRstNode]
  hasToc*: bool
  findFile*: FindFileHandler
  msgHandler*: MsgHandler
  outDir*: string            ## output directory, initialized by docgen.nim
  destFile*: string          ## output (HTML) file, initialized by docgen.nim
  filenames*: RstFileTable
  filename*: string          ## source Nim or Rst file
  meta*: array[MetaEnum, string]
  ## \
  ## Stores the empty string or the last headline/overline found in the rst
  ## document, so it can be used as a prettier name for term index generation.
  ## \
  ## Keeps count of same text index terms to generate different identifiers
  ## for hyperlinks. See renderIndexTerm proc for details.
  id*: int                   ## A counter useful for generating IDs.
  onTestSnippet*: proc (d: var RstGenerator; filename, cmd: string; status: int;
                        content: string) {....gcsafe.}
  escMode*: EscapeMode

Исходный код Изменить

Константы

IndexExt = ".idx": Исходный код Изменить

Процедуры

proc defaultConfig(): StringTableRef {....raises: [], tags: [], forbids: [].}: Возвращает конфигурацию по умолчанию для генерации встроенного HTML.

Возвращаемый StringTableRef содержит параметры, используемые HTML-движком для построения конечного вывода. Для получения информации о том, что представляют собой эти параметры и их назначение, обратитесь к файлу config/nimdoc.cfg, входящем в состав компилятора.

Единственное отличие между содержимым этого файла и значениями, предоставляемыми этим процессом, — это переменная doc.file. Переменная doc.file файла конфигурации содержит HTML для построения автономных страниц, в то время как этот процесс возвращает только содержимое для процессов, таких как rstToHtml, для генерации минимального HTML.
Исходный код Редактировать
proc esc(target: OutputTarget; s: string; splitAfter = -1; escMode = emText): string {. ...raises: [], tags: [], forbids: [].}: Экранирует HTML. Исходный код Редактировать
proc escChar(target: OutputTarget; dest: var string; c: char; escMode: EscapeMode) {.inline, ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc formatNamedVars(frmt: string; varnames: openArray[string]; varvalues: openArray[string]): string {. ...raises: [ValueError], tags: [], forbids: [].}: Исходный код Редактировать
proc initRstGenerator(g: var RstGenerator; target: OutputTarget; config: StringTableRef; filename: string; findFile: FindFileHandler = nil; msgHandler: MsgHandler = nil; filenames = default(RstFileTable); hasToc = false) {. ...raises: [ValueError], tags: [], forbids: [].}: Инициализирует RstGenerator.

Необходимо вызвать эту функцию перед использованием RstGenerator с другими функциями в этом модуле. Передайте значение, отличное от nil StringTableRef, в качестве config с параметрами, используемыми генератором HTML-вывода. Если вы не знаете, что использовать, передайте результаты функции defaultConfig() <#defaultConfig>_.

Параметр filename будет использоваться для обработки ошибок и создания гиперссылок на файл в индексе, но вы можете передать сюда пустую строку, если анализируете поток в памяти. Если filename оканчивается на расширение .nim, заголовок документа будет автоматически установлен как Module filename. Этот заголовок по умолчанию может быть переопределён встроенным rst, но это помогает улучшить сгенерированный индекс, если заголовок не найден.

Типы RstParseOptions, FindFileHandler и MsgHandler определены в модуле packages/docutils/rst. options выбирает поведение rst-парсера.

findFile — это функция, используемая директивой rst include и другими. Цель этой функции — изменять или фильтровать пути. Она получает пути, указанные в документе rst, и должна возвращать действительный путь к существующим файлам или пустую строку в противном случае. Если вы передадите nil, будет использоваться функция по умолчанию, которая возвращает входной путь только в случае, если файл существует. Одно из применений этой функции — преобразование относительных путей, найденных в документе, в абсолютные пути, что полезно, если rst-файл и ресурсы, на которые он ссылается, не находятся в той же директории, что и текущий рабочий каталог.

msgHandler — это функция для обработки сообщений об ошибках пользователя. Она будет вызвана с именем файла, строкой, столбцом и типом любой ошибки, обнаруженной во время разбора. Если вы передадите nil, будет использоваться обработчик сообщений по умолчанию, который записывает сообщения в стандартный вывод.

Пример:

import packages/docutils/rstgen var gen: RstGenerator gen.initRstGenerator(outHtml, defaultConfig(), "filename", {})
Исходный код Редактировать
proc mergeIndexes(dir: string): string {....raises: [OSError, IOError, ValueError], tags: [ReadDirEffect, ReadIOEffect], forbids: [].}: Объединяет все файлы индекса в dir и возвращает сгенерированный индекс в формате HTML.

Эта функция сначала просканирует dir в поисках файлов индекса с расширением .idx, созданных ранее командами, такими как nim doc|rst2html, которые используют переключатель --index:on. Эти файлы индекса являются результатом вызовов setIndexTerm() и writeIndexFile(), поэтому они представляют собой простые файлы с табуляцией.

По соглашению эта функция разделит файлы индекса на две категории: документация и API. Индексы API будут объединены в один большой отсортированный индекс, составляющий основную часть конечного индекса. Это подходит для документации API, так как многие символы повторяются в разных модулях. С другой стороны, индексы документации представляют собой в основном таблицы содержания плюс несколько специальных маркеров. Эти документы будут отображаться в отдельном разделе, который пытается сохранить порядок и иерархию символов в файле индекса.

Для различения файлов документации и API используется соглашение: индексы, содержащие одну запись без символа HTML-хеша (#), будут считаться documentation, так как эта запись без хеша является явным заголовком документа. Индексы без явной записи будут считаться generated API из исходного файла .nim.

Возвращает объединённый и отсортированный индекс в единый HTML-блок, который можно в дальнейшем встраивать в шаблоны nimdoc.
Исходный код Редактировать
proc nextSplitPoint(s: string; start: int): int {....raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc prettyLink(file: string): string {....raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc readIndexDir(dir: string): tuple[modules: seq[string], symbols: seq[IndexEntry], docs: IndexedDocs] {. ...raises: [OSError, IOError, ValueError], tags: [ReadDirEffect, ReadIOEffect], forbids: [].}: Обходит dir , читая файлы .idx и преобразуя их в элементы IndexEntry.

Возвращает список найденных имён модулей, список свободных записей символов и различные индексы документации. Список модулей отсортирован. Подробности см. в документации mergeIndexes.
Исходный код Редактировать
proc renderCodeLang(result: var string; lang: SourceLanguage; code: string; target: OutputTarget) {....raises: [ValueError], tags: [], forbids: [].}: Исходный код Редактировать
proc renderIndexTerm(d: PDoc; n: PRstNode; result: var string) {. ...raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}: Отображает строку, помеченную маркерами `foobar`:idx:.

Кроме того, добавляет заключённый текст в индекс как термин. Поскольку нас интересуют различные экземпляры одного и того же термина с различными записями, используется таблица для отслеживания количества предыдущих появлений термина, чтобы задать разные идентификаторы для каждого.
Исходный код Редактировать
proc renderNimCode(result: var string; code: string; target: OutputTarget) {. ...raises: [ValueError], tags: [], forbids: [].}: Исходный код Редактировать
proc renderRstToOut(d: var RstGenerator; n: PRstNode; result: var string) {. ...gcsafe, raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}: Записывает в result rst-аст n с использованием конфигурации d.

Перед использованием этой функции необходимо инициализировать RstGenerator с initRstGenerator и проанализировать rst-файл с помощью rstParse из модуля packages/docutils/rst. Пример:

# ...configure gen and rst vars... var generatedHtml = "" renderRstToOut(gen, rst, generatedHtml) echo generatedHtml
Исходный код Редактировать
proc renderTocEntries(d: var RstGenerator; j: var int; lvl: int; result: var string) {....raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}: Исходный код Редактировать

proc rstToHtml(s: string; options: RstParseOptions; config: StringTableRef; msgHandler: MsgHandler = rst.defaultMsgHandler): string {....gcsafe, raises: [Exception, ValueError, KeyError], tags: [RootEffect, ReadIOEffect, ReadEnvEffect], forbids: [].}: Преобразует входную строку rst в встраиваемый HTML.

Эта вспомогательная процедура анализирует любую входную строку с использованием разметки rst (она не обязана быть полным документом!) и возвращает встраиваемый фрагмент HTML. Процедура предназначена для использования в онлайн-средах без доступа к значимому файловой системе, и поэтому директивы rst include работать не будут. Объяснение параметра config см. в процедуре initRstGenerator. Пример:

import packages/docutils/rstgen, strtabs echo rstToHtml("*Hello* **world**!", {}, newStringTable(modeStyleInsensitive)) # --> <em>Hello</em> <strong>world</strong>!

Если вам нужно разрешить директиву rst include или изменить сгенерированный вывод, вы должны создать собственный RstGenerator с initRstGenerator и связанными процедурами.
Исходный код Редактировать
proc rstToLatex(rstSource: string; options: RstParseOptions): string {.inline, ...raises: [Exception, ValueError, KeyError], tags: [RootEffect, ReadIOEffect, ReadEnvEffect], forbids: [].}: Удобная процедура для renderRstToOut и initRstGenerator.
Пример:

doAssert rstToLatex("*Hello* **world**", {}) == """\emph{Hello} \textbf{world}"""
Исходный код Редактировать
proc setIndexTerm(d: var RstGenerator; k: IndexEntryKind; htmlFile, id, term: string; linkTitle, linkDesc = ""; line = 0) {. ...raises: [], tags: [], forbids: [].}: Добавляет term в индекс с использованием указанного идентификатора гиперссылки.

В индекс будет добавлена новая запись в формате term<tab>file#id. Часть файла будет взята из параметра htmlFile.

Параметр id будет дополнен символом решетки (#) только если его длина не равна нулю, в противном случае особый якорь не будет сгенерирован. В общем случае вы должны передавать пустое значение id только для заголовка автономных документов rst (они являются специальными для процедуры mergeIndexes(), см. Формат файла индекса (idx) для получения дополнительной информации). В отличие от других записей индекса, записи заголовка вставляются в начало накопленного буфера для сохранения логического порядка записей.

Если linkTitle или linkDesc не пустые строки, будут добавлены две дополнительные колонки со своим содержимым.

Индекс не будет записан на диск, пока не будет вызвано writeIndexFile(). Назначение индекса описано в руководстве по инструментам docgen.
Исходный код Редактировать
proc traverseForIndex(d: PDoc; n: PRstNode) {....raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}: Версия renderRstToOut, которая заполняет только записи для .idx файлов. Исходный код Редактировать
proc writeIndexFile(g: var RstGenerator; outfile: string) {....raises: [IOError], tags: [WriteIOEffect], forbids: [].}: Записывает текущий буфер индекса в указанный выходной файл.

Ранее необходимо добавить записи в индекс с помощью процедуры setIndexTerm(). Если индекс пустой, файл не будет создан.
Исходный код Редактировать