documentation/python: ensure relative includes work in parsed docs.

This is quite bad, but ... at least something.

diff --git a/documentation/python.py b/documentation/python.py
index 300e8cfccdab79ab3887ac9ce63c6d5c9fe9b975..91366bdb63f303922fc237f038feec69c5462a00 100755 (executable)
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -1956,8 +1956,11 @@ def publish_rst(state: State, source, *, source_path=None, translator_class=m.ht
     # Docutils uses a deprecated U mode for opening files, so instead of
     # monkey-patching docutils.io.FileInput to not do that (like Pelican does),
     # I just read the thing myself.
-    # TODO for external docs it *somehow* needs to supply the filename and line
-    # range to it for better error reporting, this is too awful
+    # TODO for external docs it *somehow* needs to supply the *proper* filename
+    #   and line range to it for better error reporting and relative includes,
+    #   this is too awful
+    if not source_path:
+        source_path=os.path.join(state.config['INPUT'], "file.rst")
     pub.set_source(source=source, source_path=source_path)
     pub.publish()
 
@@ -1967,7 +1970,7 @@ def publish_rst(state: State, source, *, source_path=None, translator_class=m.ht
     return pub
 
 def render_rst(state: State, source):
-    return publish_rst(state, source, source_path=None).writer.parts.get('body').rstrip()
+    return publish_rst(state, source).writer.parts.get('body').rstrip()
 
 class _SaneInlineHtmlTranslator(m.htmlsanity.SaneHtmlTranslator):
     # Unconditionally force compact paragraphs. This means the inline HTML
@@ -2051,7 +2054,7 @@ def render_doc(state: State, filename):
         docutils.utils.extract_options = _docutils_extract_options
         docutils.utils.assemble_option_dict = _docutils_assemble_option_dict
 
-        publish_rst(state, f.read())
+        publish_rst(state, f.read(), source_path=filename)
 
         docutils.utils.extract_options = prev_extract_options
         docutils.utils.assemble_option_dict = prev_assemble_option_dict

diff --git a/documentation/test_python/content/content.html b/documentation/test_python/content/content.html
index dbbf096a52b729747354a1991c692cebb7693506..b21bebd87b82a4f4832285c37482990751470944 100644 (file)
--- a/documentation/test_python/content/content.html
+++ b/documentation/test_python/content/content.html
@@ -39,7 +39,10 @@
           </ul>
         </div>
 <p>This is detailed module docs. I kinda <em>hate</em> how it needs to be indented,
-tho.</p>
+tho. Below is an included file to test file path is supplied somewhat
+correctly (relative to the input dir):</p>
+<pre># This module has an external summary
+</pre>
         <section id="namespaces">
           <h2><a href="#namespaces">Modules</a></h2>
           <dl class="m-doc">

diff --git a/documentation/test_python/content/docs.rst b/documentation/test_python/content/docs.rst
index 7ab0eed2f86837196f24772e5f814c27b9c3c71a..1486c0279b84adc80a12e8e5319b93351e94b2f1 100644 (file)
--- a/documentation/test_python/content/docs.rst
+++ b/documentation/test_python/content/docs.rst
@@ -14,7 +14,11 @@
     :data ANOTHER_DOCUMENTED_INSIDE_MODULE: In-module summary for another data
 
     This is detailed module docs. I kinda *hate* how it needs to be indented,
-    tho.
+    tho. Below is an included file to test file path is supplied somewhat
+    correctly (relative to the input dir):
+
+    .. include:: content/submodule.py
+        :literal:
 
 .. py:module:: content.docstring_summary