remoteinclude

remoteinclude is an extension for Sphinx that enables RST file inclusion from remote sources.

Warning

Including text from a remote source is a security risk, as the text is parsed after inclusion. Include files from trusted sources only.

Usage

Install chios, then add remoteinclude to the list of extensions in conf.py:
```
extensions = ['chios.remoteinclude']
```
Use the remote-include directive to fetch a remote RST file and include it:
```
.. remote-include:: https://example.com/rawsource.rst
```
Important

The remote-include directive does not follow references to other remote files within a downloaded file. In other words, toctree, :ref:, and similar markup fails because the referenced files are not locally available.

Using a remote file in a toctree

The toctree directive does not allow include as a child. To use a remote file in a toctree:

Create an RST file in your source directory with an appropriate name:
```
$ touch doc/myfile.rst
```

Use the remote-include directive in that file:

.. remote-include:: www.example.com/myfile.rst

You can now reference the local file in a toctree:

.. toctree::

   intro.rst
   chapter.rst
   myfile.rst

Troubleshooting

If a remote-include is empty in the HTML output, it is likely that the given link could not be resolved. Check the Sphinx build messages for a warning:

index.rst:32: WARNING: Unable to resolve https://example.com/rawsource.rst

Code listing

A Sphinx extension that enables RST includes from remote sources.

https://github.com/kallimachos/chios

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class remoteinclude.RemoteInclude(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Create remote-include directive.

run()[source]: Return rel path to a downloaded file as include node argument.

remoteinclude.setup(app) → dict[source]

Set up Sphinx extension.

Parameters: app – Sphinx application context.