search

executablebooks / sphinx-examples

A Sphinx extension to create examples of source markdown and the result of rendering it.
https://ebp-sphinx-examples.readthedocs.io/en/latest/
MIT License
7 stars 1 forks source link

0.0.5: documentation build fails #9

Open kloczek opened 2 years ago

kloczek commented 2 years ago

Describe the bug

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 v5.0.2
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English).

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 430, 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_examples'

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 433, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname,
sphinx.errors.ExtensionError: Could not import extension sphinx_examples (exception: No module named 'sphinx_examples')

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

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,5 +1,9 @@
 # -- Project information -----------------------------------------------------

+import sys
+import os
+sys.path.insert(0, os.path.abspath("../src"))
+
 project = "Sphinx Examples"
 copyright = "2022, Executable Books"
 author = "Executable Books Community"

Than on building documetation sphinx fails with call trace

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.2
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English).
making output directory... done
myst v0.17.2: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=['colon_fence'], linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, footnote_transition=True, sub_delimiters=('{', '}'), words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] reference
/home/tkloczko/rpmbuild/BUILD/sphinx-examples-0.0.5/docs/index.md:90: ERROR: Unknown directive type "margin".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-examples.3 { reference changelog } failed

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 329, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 285, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 352, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.8/site-packages/sphinx/util/__init__.py", line 517, in wrapper
    return f(*args, **kwargs)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/manpage.py", line 98, in write
    docwriter.write(largetree, destination)
  File "/usr/lib/python3.8/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 29, in translate
    visitor = self.builder.create_translator(self.document, self.builder)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 122, in create_translator
    return self.app.registry.create_translator(self, *args)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 347, in create_translator
    setattr(translator, 'visit_' + name, MethodType(visit, translator))
TypeError: first argument must be callable

Exception occurred:
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 347, in create_translator
    setattr(translator, 'visit_' + name, MethodType(visit, translator))
TypeError: first argument must be callable
The full traceback has been saved in /tmp/sphinx-err-ad1yzd8d.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
[tkloczko@devel-g2v SPECS]$ cat /tmp/sphinx-err-ad1yzd8d.log
# Sphinx version: 5.0.2
# Python version: 3.8.13 (CPython)
# Docutils version: 0.17.1 release
# Jinja2 version: 3.1.1
# Last messages:
#   pickling environment...
#   done
#   checking consistency...
#   done
#   writing...
#   python-sphinx-examples.3 {
#   reference
#   changelog
#   }
#   failed
# Loaded extensions:
#   sphinx.ext.mathjax (5.0.2) from /usr/lib/python3.8/site-packages/sphinx/ext/mathjax.py
#   sphinxcontrib.applehelp (1.0.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/applehelp/__init__.py
#   sphinxcontrib.devhelp (1.0.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/devhelp/__init__.py
#   sphinxcontrib.htmlhelp (2.0.0) from /usr/lib/python3.8/site-packages/sphinxcontrib/htmlhelp/__init__.py
#   sphinxcontrib.serializinghtml (1.1.5) from /usr/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py
#   sphinxcontrib.qthelp (1.0.3) from /usr/lib/python3.8/site-packages/sphinxcontrib/qthelp/__init__.py
#   alabaster (0.7.12) from /usr/lib/python3.8/site-packages/alabaster/__init__.py
#   myst_parser (0.17.2) from /usr/lib/python3.8/site-packages/myst_parser/__init__.py
#   sphinx_copybutton (0.5.0) from /usr/lib/python3.8/site-packages/sphinx_copybutton/__init__.py
#   sphinx_design (0.2.0) from /usr/lib/python3.8/site-packages/sphinx_design/__init__.py
#   sphinx_examples (0.0.5) from /home/tkloczko/rpmbuild/BUILD/sphinx-examples-0.0.5/src/sphinx_examples/__init__.py
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 329, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 285, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 352, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.8/site-packages/sphinx/util/__init__.py", line 517, in wrapper
    return f(*args, **kwargs)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/manpage.py", line 98, in write
    docwriter.write(largetree, destination)
  File "/usr/lib/python3.8/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 29, in translate
    visitor = self.builder.create_translator(self.document, self.builder)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 122, in create_translator
    return self.app.registry.create_translator(self, *args)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 347, in create_translator
    setattr(translator, 'visit_' + name, MethodType(visit, translator))
TypeError: first argument must be callable

Reproduce the bug

Run sphinx-build -n -T -b man docs build/sphinx/man in source code root directory.

List your environment

Package Version

alabaster 0.7.12 appdirs 1.4.4 attrs 22.1.0.dev0 Babel 2.10.2 Brlapi 0.8.3 build 0.8.0 charset-normalizer 2.1.0 codespell 2.1.0 cssselect 1.1.0 cycler 0.11.0 distro 1.7.0 docutils 0.17.1 extended-project 1.2.3 extras 1.0.0 fixtures 4.0.0 flit_core 3.7.1 fonttools 4.34.4 gpg 1.17.1-unknown idna 3.3 imagesize 1.4.1 importlib-metadata 4.12.0 importlib-resources 5.8.0 iniconfig 1.1.1 Jinja2 3.1.1 kiwisolver 1.4.4 libcomps 0.1.18 louis 3.22.0 lxml 4.9.1 markdown-it-py 2.1.0 MarkupSafe 2.1.1 matplotlib 3.5.2 mdit-py-plugins 0.3.0 mdurl 0.1.1 myst-parser 0.17.2 numpy 1.23.1 olefile 0.46 packaging 21.3 pbr 5.8.1 pep517 0.12.0 Pillow 9.2.0 pip 22.0.4 pluggy 1.0.0 py 1.11.0 Pygments 2.12.0 PyGObject 3.42.1 pyparsing 3.0.9 pyrsistent 0.18.1 pytest 7.1.2 python-dateutil 2.8.2 pytz 2022.1 PyYAML 6.0 requests 2.28.1 rpm 4.17.0 scour 0.38.2 simple-project 1.2.3 six 1.16.0 snowballstemmer 2.2.0 Sphinx 5.0.2 sphinx-copybutton 0.5.0 sphinxcontrib-applehelp 1.0.2.dev20220714 sphinxcontrib-devhelp 1.0.2.dev20220714 sphinxcontrib-htmlhelp 2.0.0 sphinxcontrib-jsmath 1.0.1.dev20220712 sphinxcontrib-qthelp 1.0.3.dev20220712 sphinxcontrib-serializinghtml 1.1.5 testtools 2.5.0 tomli 2.0.1 traitlets 5.3.0 typing_extensions 4.2.0 urllib3 1.26.9 wheel 0.37.1 zipp 3.8.1

welcome[bot] commented 2 years ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada: