Директива включения Python Sphinx: игнорировать заголовок из включенного файла - PullRequest
Новая
       7

Директива включения Python Sphinx: игнорировать заголовок из включенного файла

0 голосов
/ 04 февраля 2019

Я нашел директиву .. include:: очень полезной для повторного использования текста: одни и те же части могут быть вставлены в разные документы.

Но есть проблема с уровнями заголовков.

Например, еслиУ меня есть part.rst с заголовком второго уровня

part.rst

Header level 2
----------------

My text to be included

и включаю его в различные документы с различными уровнями заголовка

doc 1

Header level 1
================

.. include::  part.rst

doc2

Header level 2
----------------

.. include::  part.rst

doc 3

Header level 3
~~~~~~~~~~~~~~~~~

.. include::  part.rst

Это будет всегда один и тот же уровень 2. Не могу контролировать его.

Я читал о sphinx.ext.ifconfig - Включите контент на основе конфигурации , я могу обернуть заголовки с помощью

part.rst

.. ifconfig:: hide_part_rst_title

    Header level 2
    ----------------

My text to be included

Но этопохоже на создание многих переменных в случае множества файлов деталей.

Может быть, есть более элегантный способ?

Как включить файлы .rst без оригинальных заголовков?Если я обрежу это, я мог бы добавить заголовок в каждом месте, как это 

.. doc 1
Header level 1
================

Included text header
---------------
.. include::  part.rst

.. doc 2
Header level 2
----------------

Included text header
======================
.. include::  part.rst

.. doc 3
Header level 3
~~~~~~~~~~~~~~~~~

Included text header
~~~~~~~~~~~~~~~~~~~~~~~
.. include::  part.rst

1 Ответ

0 голосов
/ 04 февраля 2019

На странице директив Sphinx нет подробностей для директивы .. include::, но есть ссылка на Включая фрагмент внешнего документа .

Найденочто есть некоторые опции для .. include:: директивы

Следующие опции распознаются: 

start-line : integer

Будет включен только контент, начинающийся с этой строки,(Как обычно в Python, первая строка имеет индекс 0 и отрицательные значения отсчитываются от конца.) 

end-line : integer

Будет включено только содержимое до (но исключая) этой строки.

start-after : text to find in the external data file

Будет включен только контент после первого появления указанного текста.

end-before : text to find in the external data file

Будет включено только содержимое до первого вхождения указанного текста (но после любого после текста). 

literal : flag (empty)

Весь включенный текст вставляется в документ какодин буквальный блок.

code : formal language (optional)

Аргумент и содержимое включенного файла передаются директиве кода (полезно для списков программ).(Новое в Docutils 0.9) 

number-lines : [start line number]

Перед каждой строкой кода указывается номер строки.Необязательный аргумент - это номер первой строки (по умолчанию 1).Работает только с кодом или литералом.(Новое в Docutils 0.9) 

encoding : name of text encoding

Кодировка текста внешнего файла данных.По умолчанию используется значение input_encoding для документа.

tab-width : integer

Количество пробелов для расширения с помощью вкладок.Отрицательное значение препятствует расширению жестких вкладок.По умолчанию используется параметр конфигурации tab_width.

При code или literal также распознаются общие опции :class: и :name:.

Возможно объединение start/end-line и start-after/end-before.Текстовые маркеры будут искать в указанных строках (далее ограничивая включенное содержимое).

, но нет примеров как использовать этот синтаксис.

ПросмотрСоседская директива raw опробована и теперь она работает!

Этот код включает part.rst из 5-й строки (после моего заголовка) 

.. include::  part.rst
    :start-line: 5

или если изменить part.rst addind aспециальная метка 

Header level 2
----------------
.. include_after_this_label

My text to be included

Я мог бы использовать одну и ту же метку в нескольких файлах, чтобы включить файл Flexible 

.. include::  part.rst
    :start-after: .. include_after_this_label
...