From: Vladimír Vondruš <mosra@centrum.cz>
Date: Fri, 30 Aug 2019 17:59:08 +0000 (+0200)
Subject: documentation/python: ensure relative includes work in parsed docs.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=5e63b3964bdf2745e6545822d55403a9166c5834;p=blog.git

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 300e8cfc..91366bdb 100755
--- 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 dbbf096a..b21bebd8 100644
--- 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 7ab0eed2..1486c027 100644
--- 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