rstgen

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

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

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

Примечание: Импортируйте packages/docutils/rstgen для использования этого модуля

Импорты

rstast, rst, highlite

Типы

OutputTarget = enum outHtml, outLatex: какой тип документа генерировать Исходный код Изменить
MetaEnum = enum metaNone, metaTitle, metaSubtitle, metaAuthor, metaVersion: Исходный код Изменить
RstGenerator = object of RootObj target*: OutputTarget config*: StringTableRef splitAfter*: int listingCounter*: int tocPart*: seq[TocEntry] hasToc*: bool theIndex: string options*: RstParseOptions findFile*: FindFileHandler msgHandler*: MsgHandler outDir*: string ## output directory, initialized by docgen.nim destFile*: string ## output (HTML) file, initialized by docgen.nim filename*: string ## source Nim or Rst file meta*: array[MetaEnum, string] currentSection: 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. seenIndexTerms: Table[string, int] ## \ ## 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): Исходный код Изменить

Константы

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

Процедуры

proc prettyLink(file: string): string {...}{.raises: [], tags: [].}

Исходный код Редактировать

proc initRstGenerator(g: var RstGenerator; target: OutputTarget; config: StringTableRef; filename: string; options: RstParseOptions; findFile: FindFileHandler = nil; msgHandler: MsgHandler = nil) {...}{.raises: [ValueError], tags: [].}

Инициализирует 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 writeIndexFile(g: var RstGenerator; outfile: string) {...}{.raises: [IOError], tags: [WriteIOEffect].}

Записывает текущий буфер индекса в указанный выходной файл.

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

Исходный код Редактировать

proc escChar(target: OutputTarget; dest: var string; c: char) {...}{.inline, raises: [], tags: [].}

Исходный код Редактировать

proc nextSplitPoint(s: string; start: int): int {...}{.raises: [], tags: [].}

Исходный код Редактировать

proc esc(target: OutputTarget; s: string; splitAfter = -1): string {...}{.raises: [], tags: [].}

Экранирует HTML. Исходный код Редактировать

proc setIndexTerm(d: var RstGenerator; htmlFile, id, term: string; linkTitle, linkDesc = "") {...}{.raises: [], tags: [].}

Добавляет term в индекс, используя указанный идентификатор гиперссылки.

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

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

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

Индекс не будет записан на диск, пока не будет вызван writeIndexFile(). Цель индекса описана в руководстве по инструментам docgen.

Исходный код Редактировать

proc renderIndexTerm(d: PDoc; n: PRstNode; result: var string) {...}{. raises: [Exception, ValueError], tags: [RootEffect].}

Отображает строку, оформленную маркерами `foobar`:idx:.

Дополнительно добавляет заключённый текст в индекс как термин. Так как нас интересуют разные экземпляры одного и того же термина, чтобы у них были разные записи, используется таблица, чтобы отслеживать количество раз, когда термин появлялся ранее, чтобы дать разное идентификационное значение для каждого.

Исходный код Редактировать

proc mergeIndexes(dir: string): string {...}{.raises: [OSError, IOError, ValueError], tags: [ReadDirEffect, ReadIOEffect].}

Объединяет все файлы индекса в dir и возвращает сгенерированный индекс в формате HTML.

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

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

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

Возвращает объединённые и отсортированные индексы в один HTML-блок, который можно дальше встроить в шаблоны nimdoc.

Исходный код Редактировать

proc renderTocEntries(d: var RstGenerator; j: var int; lvl: int; result: var string) {...}{.raises: [ValueError], tags: [].}

Исходный код Редактировать

proc renderRstToOut(d: var RstGenerator; n: PRstNode; result: var string) {...}{. raises: [Exception, ValueError], tags: [RootEffect].}

Записывает в 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 formatNamedVars(frmt: string; varnames: openArray[string]; varvalues: openArray[string]): string {...}{. raises: [ValueError], tags: [].}

Исходный код Редактировать

proc defaultConfig(): StringTableRef {...}{.raises: [], tags: [].}

Возвращает конфигурацию по умолчанию для встроенного генерации HTML.

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

Единственное отличие между содержимым этого файла и значениями, предоставляемыми этой процедурой, — это переменная doc.file. Переменная doc.file файла конфигурации содержит HTML для создания автономных страниц, в то время как эта процедура возвращает только содержимое для процедур, таких как rstToHtml , для генерации минимального HTML.

Исходный код Редактировать

proc rstToHtml(s: string; options: RstParseOptions; config: StringTableRef): string {...}{. raises: [ValueError, EParseError, IOError, Exception], tags: [WriteIOEffect, ReadEnvEffect, RootEffect].}

Преобразует входную строку 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: [ValueError, Exception], tags: [RootEffect, ReadEnvEffect].}

Вспомогательная процедура для renderRstToOut и initRstGenerator.

Пример:

doAssert rstToLatex("*Hello* **world**", {}) == """\emph{Hello} \textbf{world}"""

Исходный код Редактировать