Python Sphinx include directive: ignore the header from included file

Question

I found .. include:: directive very useful for text reuse: the same parts could be inserted in different documents.

But there is a problem with header levels.

For example, if I have part.rst with second level header

part.rst

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

My text to be included

and include it in the different documents with various header levels

doc 1

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

.. include::  part.rst

doc2

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

.. include::  part.rst

doc 3

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

.. include::  part.rst

It will be always the same level 2. Can’t control it.

I’ve read about sphinx.ext.ifconfig – Include content based on configuration, I could wrap the headers with

part.rst

.. ifconfig:: hide_part_rst_title

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

My text to be included

But it looks like to create many variables in case of many parts files.

May be is there a more elegant way?

How to include the .rst files without original headers? If I crop this I could add a header in each place like this

.. 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

Asked By: and1er

||

Source

Answer 1

On the Sphinx documentation Directives page there are no details for .. include:: directive, but there is a link to Including an External Document Fragment.

Found that there are some options for .. include:: directive

The following options are recognized:
start-line : integer 
Only 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 : integer 
Only the content up to
(but excluding) this line will be included.
start-after : text to find in the external data file
Only the content after the first occurrence of the specified text will be included.
end-before : text to find in the external data file
Only 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 encoding 
The text encoding of the external data file.
Defaults to the document’s input_encoding.
tab-width : integer 
Number of spaces for hard tab expansion. A negative value prevents expansion
of hard tabs. Defaults to the tab_width configuration setting.

With code or literal the common options :class: and :name: are recognized
as well.

Combining start/end-line and start-after/end-before is possible. The
text markers will be searched in the specified lines (further limiting
the included content).

but no examples how to use this syntax.

Looking at neighbour raw directive tried and now it works!

This code includes the part.rst from the 5th line (after my heading)

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

or if modify part.rst addind a special label

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

My text to be included

I could use the same label in multiple files to include the file flexible

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

Answered By: and1er

Answer 2

i could do this with myst.

```{include} test.md
:start-after: "% start-after"
:end-before: "% end-before"

and defined the block i want to extract like this in another file:

% start-after

Why accessing to these informations are so hard and you have to blow your mind this much:(

% end-before

These two files are on the same directory.
Hope this helps to anyone who needs.

Answered By: klein

Python Sphinx include directive: ignore the header from included file

Question:

Answers: