Извлечение блоков текста из документов ReST: ref :? - PullRequest
Новая
       79

Извлечение блоков текста из документов ReST: ref :?

1 голос
/ 02 декабря 2011

У меня есть некоторая документация reStructuredText.Я хотел бы использовать отрывки из него в онлайн-справке.Похоже, что одним из подходов было бы «вырезать» фрагменты разметки по ссылке, например, 

.. _my_boring_section:

Introductory prose
------------------

blah blah blah

.. _my_interesting_section:

About this dialog
-----------------

talk about stuff which is relevant in contextual help

Как я могу использовать python / documenttils / sphinx для извлечения разметки для маркера _my_interesting_section?

1 Ответ

1 голос
/ 20 июня 2012

Я не уверен, как вы могли бы сделать это, кроме создания подклассов и настройки анализатора Docutils. Если вам просто нужен соответствующий раздел reStructuredText и вы не возражаете потерять часть разметки, вы можете попробовать следующее. Альтернативно, обработанную разметку (т.е. reStructuredText, преобразованную в HTML или LaTeX) для определенного раздела очень легко получить. Смотрите мой ответ на этот вопрос для примера извлечения части обработанного XML. Дайте мне знать, если вы этого хотите. Во всяком случае, здесь идет ...

Вы можете очень легко управлять reStructuredText, используя Docutils. Сначала вы можете опубликовать представление дерева документов (doctree) Docutils для reStructuredText, используя функцию Docutils publish_doctree. Эта доктрина может быть легко пройдена и найдена для определенных элементов документа, то есть разделов, с определенными атрибутами. Самый простой способ поиска конкретной ссылки на раздел - это проверить атрибут ids самого документа. doctree.ids - это просто словарь, содержащий сопоставление всех ссылок на соответствующую часть документа. 

from docutils.core import publish_doctree

s = """.. _my_boring_section:

Introductory prose
------------------

blah blah blah

.. _my_interesting_section:

About this dialog
-----------------

talk about stuff which is relevant in contextual help
"""

# Parse the above string to a Docutils document tree:
doctree = publish_doctree(s)

# Get element in the document with the reference id `my-interesting-section`:
ids = 'my-interesting-section'

try:
    section = document.ids[ids]
except KeyError:
    # Do some exception handling here...
    raise KeyError('No section with ids {0}'.format(ids))

# Can also make sure that the element we found was in fact a section:
import docutils.nodes
isinstance(section, docutils.nodes.section) # Should be True

# Finally, get section text
section.astext()

# This will print:
# u'About this dialog\n\ntalk about stuff which is relevant in contextual help'

Теперь разметка потеряна. Если это замечание слишком необычное, было бы легко вставить несколько черточек под первой строкой приведенного выше результата, чтобы вернуться к заголовку раздела. Я не уверен, что вам нужно сделать для более сложной встроенной разметки. Надеемся, что вышеизложенное является хорошей отправной точкой для вас.

Примечание : при запросе doctree.ids атрибут ids, который я передаю, немного отличается от определения в reStructuredText: начальное подчеркивание удалено, а все остальные подчеркивания заменены на - s. Вот как Docutils нормализует ссылки. Было бы очень просто написать функцию для преобразования ссылок reStructuredText во внутреннее представление Docutils. В противном случае, я уверен, что если вы покопаетесь в Docuitls, вы сможете найти процедуру, которая делает это.

...