Global включить в реструктурированный текст

Question

Я использую reStructuredText для своего блога/веб-сайта, и я хочу добавить глобальный файл include. У меня есть доступ к, и я рад, чтобы изменить файл настроек я использую для создания выходного HTML, я просто не могу понять синтаксис как:

1. добавления по умолчанию включает файл анализатор
2. определения директивы/инлайн-роли, и т.д. в Python с Docutils в питоне

Я попытался чтением исходного кода и документации и просто найти его немного трудно следовать. Я надеюсь, что я просто пропустил что-то супер-очевидное, но я хотел бы сделать что-то вроде следующего (первой части только то, что уже есть - вы можете увидеть rest of the file in the jekyll-rst plugin source (links right to it)

import sys 
from docutils.core import publish_parts 
from optparse import OptionParser 
from docutils.frontend import OptionParser as DocutilsOptionParser 
from docutils.parsers.rst import Parser 

# sets up a writer that is then called to parse rst pages repeatedly 
def transform(writer=None, part=None): 
    p = OptionParser(add_help_option=False) 

    # Collect all the command line options 
    docutils_parser = DocutilsOptionParser(components=(writer, Parser())) 
    for group in docutils_parser.option_groups: 
     p.add_option_group(group.title, None).add_options(group.option_list) 

    p.add_option('--part', default=part) 

    opts, args = p.parse_args() 


# ... more settings, etc 

# then I just tell the parser/writer to process specified file X.rst every time 
# (or alternately a python file defining more roles...but nicer if in rst) 

Есть ли простой способ сделать это? Было бы здорово определить файл defaults.rst и каждый раз загружать его.

EDIT: Вот несколько примеров того, что я хотел бы включить в глобальном масштабе (обычай директивы тоже были бы хороши, но я, вероятно, напишу их в коде)

.. role:: raw-html(raw) 
    :format: html 

.. |common-substitution| replace:: apples and orange 

.. |another common substitution| replace:: etc 

Answer 1

Я не совсем уверен, понимаю ли я этот вопрос. Вы хотите определить несколько, например, замещений в каком-то файле, и иметь их доступными во всех других файлах reStructuredText, или вы хотите включить в свои выходные файлы некоторые распространенные HTML-файлы? Вы можете уточнить свой вопрос?

Если это первое, что вы хотите сделать, вы можете использовать директиву include, как я опишу в this answer.

В качестве альтернативы, если вы хотите, чтобы какой-то общий HTML-код включался в сгенерированный вывод, попробуйте скопировать и отредактировать файл template.txt, который включен в модуль path/to/docutils/writers/html4css1/. Вы можете включить произвольные элементы HTML в этот файл и изменить макет HTML, созданный Docutils. Ни один из этих методов не требует изменения исходного кода Docuitls, что всегда является преимуществом.

Редактировать: Я не думаю, что можно установить флаг для установки файла include с помощью Docuitls. Однако, если вы можете использовать Sphinx, который основан на Docuitls, но имеет нагрузку расширений, тогда этот пакет имеет настройку rst_prolog, которая делает именно то, что вам нужно (см. this answer). rst_prolog is:

Строка reStructuredText, которая будет включена в начале каждого исходного файла, который считывается.

Answer 2

Мне было нужно одно и то же: способ иметь файлы глобальных reStructuredText, автоматически импортируемых в каждую статью reStructuredText, без необходимости указывать их каждый раз вручную.

Одним из путей решения этой проблемы заключается в следующем плагин:

import os 
from pelican import signals 
from pelican.readers import RstReader 


class RstReaderWrapper(RstReader): 
     enabled = RstReader.enabled 
     file_extensions = ['rst'] 

     class FileInput(RstReader.FileInput): 
      def __init__(self, *args, **kwargs): 
       RstReader.FileInput_.__init__(self, *args, **kwargs) 
       self.source = RstReaderWrapper.SourceWrapper(self.source) 

     # Hook into RstReader 
     RstReader.FileInput_ = RstReader.FileInput 
     RstReader.FileInput = FileInput 

     class SourceWrapper(): 
      """ 
       Mimics and wraps the result of a call to `open` 
      """ 
      content_to_prepend = None 

      def __init__(self, source): 
       self.source = source 

      def read(self): 
       content = self.source.read() 
       if self.content_to_prepend is not None: 
        content = "{}\n{}".format(self.content_to_prepend, content) 
       return content 

      def close(self): 
       self.source.close() 


def process_settings(pelicanobj): 
     include_files = pelicanobj.settings.get('RST_GLOBAL_INCLUDES', []) or [] 
     base_path = pelicanobj.settings.get('PATH', ".") 

     def read(fn): 
      with open(os.path.join(base_path, fn), 'r') as res: 
       content = res.read() 
       return ".. INLCUSION FROM {}\n{}\n".format(fn, content) 

     inclusion = "".join(map(read, include_files)) if include_files else None 
     RstReaderWrapper.SourceWrapper.content_to_prepend = inclusion 


def register(): 
signals.initialized.connect(process_settings) 

Использование короче:

• Создать плагин из приведенного выше кода (лучший клонировать repository от GitHub)
• Импорт плагин (приспособить PLUGINS в pelicanconf.py)
• Определите список файлов RST (относительные пути к корню проекта) до включают в себя, установив переменную RST_GLOBAL_INCLUDES в pelicanconf.py

Пожалуйста, обратите внимание, что пеликан и Docutils оба не предназначены, чтобы позволить этому. Ни один сигнал не предоставляется, который обеспечивает чистый доступ к исходному содержимому исходного файла до начала обработки, а также нет возможности перехватить структуру, считывающую файл «обычным способом» (например, подклассы, изменение жестко настроенной конфигурации и т. Д.), , Этот плагин подклассифицирует внутренний класс FileInput из RstReader и устанавливает класс класса RstReader.FileInput в подкласс. Также объекты файла python эмулируются через SourceWrapper. Тем не менее, этот подход работает для меня и не является громоздким в повседневном рабочем процессе.

Я знаю, что этот вопрос с 2012 года, но я думаю, что этот ответ может быть полезен другим.