CODEWITHSUNDEEP
pythonpython-sphinxrestructuredtext
and1er
and1er

Reputation: 1101

Python Sphinx include directive: ignore the header from included file

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

Upvotes: 6

Views: 5292

Answers (2)

klein
klein

Reputation: 49

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.

Upvotes: 1

and1er
and1er

Reputation: 1101

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

Upvotes: 11

Related Questions