0.2.8: sphinx is failing and some refferences warnings

[kloczek]

Looks like sphinx is failing because missing entries in sys.path

+ /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/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 20, in <module>
    import autodocsumm
ModuleNotFoundError: No module named 'autodocsumm'

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 202, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 165, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 345, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 20, in <module>
    import autodocsumm
ModuleNotFoundError: No module named 'autodocsumm'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 20, in <module>
    import autodocsumm
ModuleNotFoundError: No module named 'autodocsumm'

This can be fixed by patch:

--- a/docs/conf.py~     2022-04-19 19:21:53.000000000 +0000
+++ b/docs/conf.py      2022-04-19 19:28:05.964287059 +0000
@@ -17,12 +17,13 @@
 import os.path as osp
 import re
 import six
-import autodocsumm

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(osp.dirname(__file__)))
+sys.path.append(os.path.abspath('..'))
+
+import autodocsumm

 # -- General configuration ------------------------------------------------

However after that sphinx fails in other place

[tkloczko@devel-g2v autodocsumm-0.2.8]$ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
[autosummary] generating autosummary for: api/autodocsumm.rst, conf_settings.rst, demo_class.rst, demo_grouper.rst, demo_module.rst, examples.rst, index.rst
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
Failed to import dummy.
Possible hints:
* ModuleNotFoundError: No module named 'dummy'
* KeyError: 'dummy'
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
loading intersphinx inventory from https://docs.python.org/3.9/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 7 added, 0 changed, 0 removed
reading sources... [ 14%] api/autodocsumm
Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/conf.py", line 395, in example_grouper
    import dummy2
ModuleNotFoundError: No module named 'dummy2'

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 276, in build_main
    app.build(args.force_all, filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 330, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 283, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 300, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 407, in read
    self._read_serial(docnames)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 428, in _read_serial
    self.read_doc(docname)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 468, in read_doc
    doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
  File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 181, in read_doc
    pub.publish()
  File "/usr/lib/python3.8/site-packages/docutils/core.py", line 217, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 101, in read
    self.parse()
  File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 89, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 170, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2769, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2096, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 154, in run
    documenter.generate(more_content=self.content)
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 978, in generate
    self.add_content(more_content)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py", line 367, in add_content
    self.add_autosummary(relative_ref_paths=True)
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py", line 296, in add_autosummary
    grouped_documenters = self.get_grouped_documenters()
  File "/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py", line 273, in get_grouped_documenters
    user_section = self.env.app.emit_firstresult(
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 457, in emit_firstresult
    return self.events.emit_firstresult(event, *args,
  File "/usr/lib/python3.8/site-packages/sphinx/events.py", line 112, in emit_firstresult
    for result in self.emit(name, *args, allowed_exceptions=allowed_exceptions):
  File "/usr/lib/python3.8/site-packages/sphinx/events.py", line 102, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function example_grouper at 0x7fd2e0adb8b0> for event 'autodocsumm-grouper' threw an exception (exception: No module named 'dummy2')

Extension error:
Handler <function example_grouper at 0x7fd2e0adb8b0> for event 'autodocsumm-grouper' threw an exception (exception: No module named 'dummy2')

As dummy.py and dummy2.py are in docs/ final patch can look like below:

+++ b/docs/conf.py      2022-04-19 19:31:22.948359190 +0000
@@ -17,12 +17,14 @@
 import os.path as osp
 import re
 import six
-import autodocsumm

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(osp.dirname(__file__)))
+sys.path.append(os.path.abspath('..'))
+sys.path.append(os.path.abspath('.'))
+
+import autodocsumm

 # -- General configuration ------------------------------------------------

Wit habove documentation build corrctly.

It is yet another issue. On building my packages I'm usimg sphinx-build command with -n swich which shows warnimgs about missing references. These are not critical issues.
Here is the output with warnings:

[tkloczko@devel-g2v autodocsumm-0.2.8]$ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
loading pickled environment... done
[autosummary] generating autosummary for: api/autodocsumm.rst, conf_settings.rst, demo_class.rst, demo_grouper.rst, demo_module.rst, examples.rst, index.rst
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
writing... python-autodocsumm.3 { conf_settings examples demo_module demo_class demo_grouper api/autodocsumm } /home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/dummy2.py:docstring of dummy2.MyClass:1:<autosummary>:1: WARNING: py:obj reference target not found: dummy2.MyClass.do_something
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/dummy2.py:docstring of dummy2.MyClass:1:<autosummary>:1: WARNING: py:obj reference target not found: dummy2.MyClass.some_attr
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/dummy2.py:docstring of dummy2.MyClass.do_something:1:<autosummary>:1: WARNING: py:obj reference target not found: dummy2.MyClass.some_other_attr
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/call_demo.py:docstring of call_demo.MyClass.do_something:1:<autosummary>:1: WARNING: py:obj reference target not found: call_demo.MyClass.do_something
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/call_demo.py:docstring of call_demo.MyClass.do_something:: WARNING: py:class reference target not found: any
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/call_demo.py:docstring of call_demo.MyClass.do_something:: WARNING: py:class reference target not found: anything else
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/docs/inline_autoclasssumm.py:docstring of inline_autoclasssumm.MyClass.do_something:1:<autosummary>:1: WARNING: py:obj reference target not found: inline_autoclasssumm.MyClass.some_attr
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoDocSummDirective:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter:3: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummClassDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
docstring of autodocsumm.AutoSummClassDocumenter.member_sections:3: WARNING: py:attr reference target not found: sphinx.ext.autodoc.Documenter.member_order
docstring of autodocsumm.AutoSummClassDocumenter.option_spec:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
docstring of autodocsumm.AutoSummClassDocumenter.priority:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ClassDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter:3: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutoSummModuleDocumenter.add_content:1:<autosummary>:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
docstring of autodocsumm.AutoSummModuleDocumenter.member_sections:3: WARNING: py:attr reference target not found: sphinx.ext.autodoc.Documenter.member_order
docstring of autodocsumm.AutoSummModuleDocumenter.option_spec:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
docstring of autodocsumm.AutoSummModuleDocumenter.priority:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:3: WARNING: py:meth reference target not found: sphinx.ext.autodoc.ModuleDocumenter.generate
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:3: WARNING: py:meth reference target not found: sphinx.ext.autodoc.ModuleDocumenter.document_members
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:10: WARNING: py:attr reference target not found: member_sections
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:18: WARNING: py:class reference target not found: sphinx.ext.autodoc.Documenter.member_order
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.AutosummaryDocumenter.get_grouped_documenters:18: WARNING: py:attr reference target not found: member_sections
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableAttributeDocumenter:: WARNING: py:class reference target not found: DocumenterBridge
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableAttributeDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableAttributeDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.AttributeDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableDataDocumenter:: WARNING: py:class reference target not found: DocumenterBridge
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableDataDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.CallableDataDocumenter:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.DataDocumenter
/home/tkloczko/rpmbuild/BUILD/autodocsumm-0.2.8/autodocsumm/__init__.py:docstring of autodocsumm.dont_document_data:: WARNING: py:class reference target not found: sphinx.Options
docstring of autodocsumm.member_options:1: WARNING: py:class reference target not found: sphinx.ext.autodoc.ModuleDocumenter
done
build succeeded, 40 warnings.

These are non-critical warnings 😄

[Chilipp]

thanks for reporting @kloczek! on readthedocs we specify that the package should be installed prior to building the docs. Isn't this an option for you instead of manipulating sys.path?

[kloczek]

thanks for reporting @kloczek! on readthedocs we specify that the package should be installed prior to building the docs. Isn't this an option for you instead of manipulating sys.path?

As you see on cost of two lines patch installation is not necessary. KISS pronciple ..
On packaging software (anything else outside python domain) installation is not needed to generate documentation. Side effect of that patch is that it guarantees that documentation will be generated not out of installed module but just build one.
copy.py file is in source tree sphinx semi configuration file. As that file will stay always in that tree there is no any other risk that such change will affect something.