Директива включения Python Sphinx: игнорировать заголовок из включенного файла
Я нашел директиву .. 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
На Страница директив документации Sphinx нет деталей для директивы .. include::, но есть ссылка на Включение фрагмента внешнего документа.
Обнаружил, что есть какие-то опции для директивы .. include::
The following options are recognized:
start-line : integerOnly the content starting from this line will be included. (As usual in Python, the first line has index 0 and negative values count from the end.)
end-line : integerOnly the content up to (but excluding) this line will be included.
start-after : text to find in the external data fileOnly the content after the first occurrence of the specified text will be included.
end-before : text to find in the external data fileOnly the content before the first occurrence of the specified text (but after any after text) will be included.
literal : flag (empty)The entire included text is inserted into the document as a single literal block.
code : formal language (optional)The argument and the content of the included file are passed to the code directive (useful for program listings). (New in Docutils 0.9)
number-lines : [start line number]Precede every code line with a line number. The optional argument is the number of the first line (defaut 1). Works only with code or literal. (New in Docutils 0.9)
encoding : name of text encodingThe text encoding of the external data file. Defaults to the document's input_encoding.
tab-width : integerNumber of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the
tab_widthconfiguration setting.With
codeorliteralthe common options:class:and:name:are recognized as well.Combining
start/end-lineandstart-after/end-beforeis possible. The text markers will be searched in the specified lines (further limiting the included content).
но нет примеров как использовать этот синтаксис.
Глядя на соседнюю директиву raw попробовал и теперь работает!
В этот код входит part.rst из 5-й строки (после моего заголовка)
.. include:: part.rst
:start-line: 5
или если изменить part.rst добавить специальную метку
Header level 2
----------------
.. include_after_this_label
My text to be included
Я мог бы использовать одну и ту же метку в нескольких файлах, чтобы включить гибкий файл.
.. include:: part.rst
:start-after: .. include_after_this_label