Embedding a html document inside of RST

Question

I have a Sphinx-based website and have specific pages on which I would like to display predefined html files that are stored in a specified directory like _static. In Django, it's possible to simply reference the file from the template using an {{%include}} tag, does something similar exist for ReStructuredText?

I would like to do something like

.. title:: Example Page

=============
Example Page
=============

Introduction to page

<insert html reference to _static folder here>

Description

And after building the website have it combine the html generated from RST and the html file specified.

Answer 1

From the docutils docs for the raw directive:

Raw data can also be read from an external file, specified in a directive option. In this case, the content block must be empty. For example:

.. raw:: html
    :file: inclusion.html

Inline equivalents of the "raw" directive can be defined via custom interpreted text roles derived from the "raw" role.

The following options are recognized:

file : string (newlines removed) The local filesystem path of a raw data file to be included.

If you are embedding only snippets and not complete valid HTML pages, then that is what you want to use. For the latter, you can still use raw, but use an <iframe>:

.. raw:: html

    <iframe src="inclusion.html"></iframe>