Is it possible to include external rst files in my documentation?

Question

I'm building a documentation for a platform that includes modules. I would like to let the documentations live in these modules repositories and include them in the "master" doc with the include command.

I tried the following :

.. include:: https://github.com/12rambau/sepal_ui_template/blob/master/doc/en.rst

But nothing was added to the file

Is it possible to use absolute link in includecommand ?

As it can be security blackhole, I doubt whether that directive accepts a URL like that. — Lex Li, Mar 05 '21 at 18:39

score 2 · Answer 1 · answered Mar 06 '21 at 04:42

No. A fully qualified URL is not relative to the document. According to the docs for the include directive:

The directive argument is the path to the file to be included, relative to the document containing the directive.

There are alternatives, including this one.

Pierrick Rambaud · Accepted Answer · 2021-08-06T12:59:50.680

My main objective is not to use the include command but to avoid code ducplication and use a file that is available on the web. based on @Steve piercy answer I came up with this solution :

In the conf.py file I copy the content of the file from github

be careful and use the raw.githubusercontent.com link to avoid importing html


# [...]
# -- Copy the modules documentation ------------------------------------------

from urllib.request import urlretrieve

urlretrieve (
    "https://raw.githubusercontent.com/12rambau/sepal_ui_template/master/doc/en.rst",
    "modules/sepal_ui_template.rst"
)

after that the file is created under modules/sepal_ui_template.rst in my documentation and I can safely access it.

It will be download again every time I rebuild my documentation.

Is it possible to include external rst files in my documentation?

2 Answers2