docs won't build without having sphinx-mdinclude already installed

[kloczek]

First of all currently it is not possible to use straight sphinx-build command to build documentation out of source tree

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 425, in load_extension
    mod = import_module(extname)
  File "/usr/lib64/python3.8/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
  File "<frozen importlib._bootstrap>", line 991, in _find_and_load
  File "<frozen importlib._bootstrap>", line 973, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'sphinx_mdinclude'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 223, in __init__
    self.setup_extension(extension)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 380, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 428, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname,
sphinx.errors.ExtensionError: Could not import extension sphinx_mdinclude (exception: No module named 'sphinx_mdinclude')

Extension error:
Could not import extension sphinx_mdinclude (exception: No module named 'sphinx_mdinclude')

This can be fixed by patch like below:

--- a/docs/conf.py~     2022-03-07 06:38:01.000000000 +0000
+++ b/docs/conf.py      2022-05-29 17:25:21.932275863 +0000
@@ -4,6 +4,10 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html

+import sys
+import os
+sys.path.insert(0, os.path.abspath(".."))
+
 # -- Project information -----------------------------------------------------

 import datetime

This patch fixes what is in the comment and that can of fix is suggested in sphinx example copy.py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

Than .. with that patch

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] index
/home/tkloczko/rpmbuild/BUILD/sphinx-mdinclude-0.5.1/docs/example.md:14: WARNING: Inline interpreted text or phrase reference start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-mdinclude.3 { example changelog } done
build succeeded, 1 warning.

[amyreese]

Is there a reason that sphinx-mdinclude can't be installed into the environment before attempting to build the docs? Building them otherwise would still require installing compatible versions of mistune and/or docutils.

[kloczek]

Is there a reason that sphinx-mdinclude can't be installed into the environment before attempting to build the docs?

Yes it is.
Build of all packages in every known me Liniux/Solaris/*BSD distros is done from non-root account.
Proposed patch quarantees as well that documentation will be generated out of source tree and not against of installed module (which amy be in different version).
Of you will look across all software outside python domain which provides generate docuemtation always such process uses as input resources not waht is installed but source tree.

Building them otherwise would still require installing compatible versions of mistune and/or docutils.

And this is not a problem because thise bits are part of the build requirements.