Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

documentation build fails with manpage sphinx builder #241

Open
kloczek opened this issue Apr 23, 2023 · 16 comments
Open

documentation build fails with manpage sphinx builder #241

kloczek opened this issue Apr 23, 2023 · 16 comments

Comments

@kloczek
Copy link

kloczek commented Apr 23, 2023

Looks like sphinx-immaterial needs to be updated for latest sphinx

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v6.1.3
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
[1/2] Loading JSON schema: apidoc/json/index_transform_schema.yml
[2/2] Loading JSON schema: apidoc/json/inheritance_schema.yml
Parsed C++ input in 0.00749 seconds
Found 19 C++ declarations
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 88 added, 0 changed, 0 removed
reading sources... [100%] task_lists
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-immaterial.3 { customization admonitions content_tabs task_lists keys code_syntax_highlighting code_annotations apidoc/index apidoc/format_signatures apidoc/python/index apidoc/python/apigen apidoc/cpp/index apidoc/cpp/external_cpp_references apidoc/cpp/cppreference apidoc/cpp/apigen apidoc/json/domain inline_icons graphviz mermaid_diagrams demo_api python_apigen_demo python_apigen_generated/Dim python_apigen_generated/Dim.__init__-unbounded python_apigen_generated/Dim.__init__-size python_apigen_generated/Dim.__init__-exclusive_max python_apigen_generated/Dim.__init__-inclusive_max python_apigen_generated/Dim.exclusive_max python_apigen_generated/Dim.inclusive_min python_apigen_generated/Dim.label python_apigen_generated/Dim.size python_apigen_generated/DimExpression python_apigen_generated/DimExpression.__getitem__ python_apigen_generated/DimExpression.diagonal python_apigen_generated/DimExpression.label python_apigen_generated/DimExpression.translate_to python_apigen_generated/DimExpression.vindex python_apigen_generated/IndexDomain python_apigen_generated/IndexDomain.__init__-components python_apigen_generated/IndexDomain.__init__-dimensions python_apigen_generated/IndexDomain.__init__-json python_apigen_generated/IndexDomain.__getitem__-identifier python_apigen_generated/IndexDomain.__getitem__-selection python_apigen_generated/IndexDomain.__getitem__-domain python_apigen_generated/IndexDomain.__getitem__-expr python_apigen_generated/IndexDomain.__getitem__-transform python_apigen_generated/IndexDomain.to_json python_apigen_generated/IndexDomain.exclusive_max python_apigen_generated/IndexDomain.inclusive_min python_apigen_generated/IndexDomain.labels python_apigen_generated/IndexDomain.origin python_apigen_generated/IndexDomain.rank python_apigen_generated/IndexDomain.shape python_apigen_generated/IndexDomain.size python_apigen_generated/DimensionSelection python_apigen_generated/DimensionSelection.foo python_apigen_generated/bar python_apigen_generated/VeryLongClassNameForTestingOutWordWrapping python_apigen_generated/VeryLongClassNameForTestingOutWordWrapping.very_long_method_name_for_testing_out_word_wrapper python_apigen_generated/Foo python_apigen_generated/Foo.bar python_apigen_generated/FooSubclass python_apigen_generated/FooSubclass.baz python_apigen_generated/FooSubclass.overloaded_method cpp_apigen_demo cpp_apigen_generated/cpp_apigen_demo.IndexInterval cpp_apigen_generated/cpp_apigen_demo.IndexInterval.IndexInterval cpp_apigen_generated/cpp_apigen_demo.IndexInterval.operator-shift_left cpp_apigen_generated/cpp_apigen_demo.IndexInterval.lower cpp_apigen_generated/cpp_apigen_demo.IndexInterval.upper cpp_apigen_generated/cpp_apigen_demo.Union cpp_apigen_generated/cpp_apigen_demo.DataOrder cpp_apigen_generated/cpp_apigen_demo.operator-shift_left cpp_apigen_generated/cpp_apigen_demo.Array cpp_apigen_generated/cpp_apigen_demo.Array.Array-data-shape cpp_apigen_generated/cpp_apigen_demo.Array.Array-convert cpp_apigen_generated/cpp_apigen_demo.Array.data cpp_apigen_generated/cpp_apigen_demo.Array.shape cpp_apigen_generated/cpp_apigen_demo.Array.order cpp_apigen_generated/cpp_apigen_demo.Array.operator-subscript specimen rst_basics rst-cheatsheet/rst-cheatsheet additional_samples subpage1 subpage1subpage1 subpage1subpage2 subpage2 } /home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.3/docs/keys.rst:72: WARNING: unknown node type: <kbd_node: >
failed

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 347, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 308, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 377, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.8/site-packages/sphinx/util/display.py", line 85, in wrapper
    return f(*args, **kwargs)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/manpage.py", line 101, in write
    docwriter.write(largetree, destination)
  File "/usr/lib/python3.8/site-packages/docutils/writers/__init__.py", line 77, in write
    self.translate()
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 34, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  [Previous line repeated 9 more times]
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/usr/lib/python3.8/site-packages/sphinx/util/docutils.py", line 588, in dispatch_departure
    super().dispatch_departure(node)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2018, in dispatch_departure
    return method(node)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2040, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: kbd_node

Exception occurred:
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2040, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: kbd_node
The full traceback has been saved in /tmp/sphinx-err-o2oh47zu.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@pers-jacek SPECS]$ cat /tmp/sphinx-err-o2oh47zu.log
# Platform:         linux; (Linux-6.1.10-200.fc37.x86_64-x86_64-with-glibc2.34)
# Sphinx version:   6.1.3
# Python version:   3.8.16 (CPython)
# Docutils version: 0.19
# Jinja2 version:   3.1.2
# Pygments version: 2.15.1

# Last messages:
#   specimen
#   rst_basics
#   rst-cheatsheet/rst-cheatsheet
#   additional_samples
#   subpage1
#   subpage1subpage1
#   subpage1subpage2
#   subpage2
#   }
#   failed

# Loaded extensions:
#   sphinx.ext.mathjax (6.1.3)
#   sphinxcontrib.applehelp (1.0.4)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.0)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   alabaster (0.7.13)
#   sphinx.ext.autodoc.preserve_defaults (6.1.3)
#   sphinx.ext.autodoc.type_comment (6.1.3)
#   sphinx.ext.autodoc.typehints (6.1.3)
#   sphinx.ext.autodoc (6.1.3)
#   sphinx.ext.doctest (6.1.3)
#   sphinx.ext.extlinks (6.1.3)
#   sphinx.ext.intersphinx (6.1.3)
#   sphinx.ext.napoleon (6.1.3)
#   sphinx.ext.todo (6.1.3)
#   sphinx.ext.viewcode (6.1.3)
#   sphinx_immaterial.theme_result (unknown version)
#   sphinx_immaterial.kbd_keys (unknown version)
#   sphinx_immaterial.apidoc.object_description_options (unknown version)
#   sphinx_immaterial.apidoc.format_signatures (unknown version)
#   sphinx_immaterial.apidoc.cpp.external_cpp_references (unknown version)
#   sphinx_immaterial.apidoc.cpp.cppreference (unknown version)
#   sphinx_immaterial.apidoc.json.domain (unknown version)
#   sphinx_immaterial.apidoc.python.apigen (unknown version)
#   sphinx_immaterial.apidoc.cpp.apigen (unknown version)
#   sphinx.ext.graphviz (6.1.3)
#   sphinx_immaterial.graphviz (unknown version)
#   sphinx_jinja (unknown version)
#   sphinx_immaterial.css_and_javascript_bundles (unknown version)
#   sphinx_immaterial.external_resource_cache (unknown version)
#   sphinx_immaterial.google_fonts (unknown version)
#   sphinx_immaterial.apidoc.apidoc_formatting (unknown version)
#   sphinx_immaterial.apidoc.python.parameter_objects (unknown version)
#   sphinx_immaterial.apidoc.python.strip_property_prefix (unknown version)
#   sphinx_immaterial.apidoc.python.type_annotation_transforms (unknown version)
#   sphinx_immaterial.apidoc.python.strip_self_and_return_type_annotations (unknown version)
#   sphinx_immaterial.apidoc.python.default (unknown version)
#   sphinx_immaterial.apidoc.cpp.signodes (unknown version)
#   sphinx_immaterial.apidoc.cpp.strip_namespaces_from_signatures (unknown version)
#   sphinx_immaterial.apidoc.cpp.cpp_resolve_c_xrefs (unknown version)
#   sphinx_immaterial.apidoc.cpp.default (unknown version)
#   sphinx_immaterial.nav_adapt (unknown version)
#   sphinx_immaterial.postprocess_html (unknown version)
#   sphinx_immaterial.apidoc.object_toc (unknown version)
#   sphinx_immaterial.search_adapt (unknown version)
#   sphinx_immaterial.apidoc.wrap_signatures (unknown version)
#   sphinx_immaterial.apidoc.generic_synopses (unknown version)
#   sphinx_immaterial.content_tabs (unknown version)
#   sphinx_immaterial.mermaid_diagrams (unknown version)
#   sphinx_immaterial.task_lists (unknown version)
#   sphinx_immaterial.code_annotations (unknown version)
#   sphinx_immaterial.default_literal_role (unknown version)
#   sphinx_immaterial.highlight_push_pop (unknown version)
#   sphinx_immaterial.inline_icons (unknown version)
#   sphinx_immaterial.custom_admonitions (unknown version)
#   sphinx_immaterial (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 347, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 308, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 377, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.8/site-packages/sphinx/util/display.py", line 85, in wrapper
    return f(*args, **kwargs)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/manpage.py", line 101, in write
    docwriter.write(largetree, destination)
  File "/usr/lib/python3.8/site-packages/docutils/writers/__init__.py", line 77, in write
    self.translate()
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 34, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  [Previous line repeated 9 more times]
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/usr/lib/python3.8/site-packages/sphinx/util/docutils.py", line 588, in dispatch_departure
    super().dispatch_departure(node)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2018, in dispatch_departure
    return method(node)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2040, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: kbd_node

Here is list of installed modules in build env

Package                       Version
----------------------------- -----------------
alabaster                     0.7.13
appdirs                       1.4.4
Babel                         2.12.1
build                         0.10.0
charset-normalizer            3.1.0
clang                         16.0.1.1
distro                        1.8.0
docutils                      0.19
exceptiongroup                1.0.0
gpg                           1.19.0
idna                          3.4
imagesize                     1.4.1
importlib-metadata            6.6.0
iniconfig                     2.0.0
Jinja2                        3.1.2
libcomps                      0.1.19
Markdown                      3.4.1
MarkupSafe                    2.1.2
packaging                     23.1
pluggy                        1.0.0
pydantic                      1.10.7
Pygments                      2.15.1
pymdown-extensions            9.11
pyproject_hooks               1.0.0
pytest                        7.3.1
python-dateutil               2.8.2
pytz                          2023.2
PyYAML                        6.0
requests                      2.28.2
setuptools                    67.6.1
setuptools-scm                7.1.0
six                           1.16.0
snowballstemmer               2.2.0
Sphinx                        6.1.3
sphinx-jinja                  2.0.2
sphinxcontrib-applehelp       1.0.4
sphinxcontrib-devhelp         1.0.2.dev20230415
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1.dev20230415
sphinxcontrib-qthelp          1.0.3.dev20230415
sphinxcontrib-serializinghtml 1.1.5
tomli                         2.0.1
typing_extensions             4.5.0
urllib3                       1.26.15
wheel                         0.40.0
zipp                          3.15.0
@2bndy5
Copy link
Collaborator

2bndy5 commented Apr 23, 2023

-b man

We've only been actively supporting the HTML builders. You may need to use a different theme for other sphinx builders.

@2bndy5
Copy link
Collaborator

2bndy5 commented Apr 23, 2023 •
edited

departing unknown node type: kbd_node

trying replacing any :keys: roles with sphinx builtin :kbd: role

@2bndy5
Copy link
Collaborator

2bndy5 commented Apr 23, 2023 •
edited

I was able to suppress the error with the following patch:

diff --git a/sphinx_immaterial/kbd_keys.py b/sphinx_immaterial/kbd_keys.py
index 5356db2..67d6fa2 100644
--- a/sphinx_immaterial/kbd_keys.py
+++ b/sphinx_immaterial/kbd_keys.py
@@ -93,6 +93,7 @@ def setup(app: Sphinx):
         kbd_node,
         html=(visit_kbd, depart_kbd),
         latex=(visit_kbd_latex, depart_kbd_latex),
+        man=(visit_kbd, depart_kbd),
     )
     return {
         "parallel_read_safe": True,

But other theme extensions would need more work to make them compatible with the ManPage builder, namely the mermaid diagrams.

@kloczek
Copy link
Author

kloczek commented Apr 23, 2023

OK one sec let me check that in my build env 😋

@kloczek
Copy link
Author

kloczek commented Apr 23, 2023 •
edited by 2bndy5

Yeah .. indeed it fails in mermaid 😞

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v6.1.3
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
[1/2] Loading JSON schema: apidoc/json/index_transform_schema.yml
[2/2] Loading JSON schema: apidoc/json/inheritance_schema.yml
Parsed C++ input in 0.00671 seconds
Found 19 C++ declarations
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 88 added, 0 changed, 0 removed
reading sources... [100%] task_lists
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-immaterial.3 { customization admonitions content_tabs task_lists keys code_syntax_highlighting code_annotations apidoc/index apidoc/format_signatures apidoc/python/index apidoc/python/apigen apidoc/cpp/index apidoc/cpp/external_cpp_references apidoc/cpp/cppreference apidoc/cpp/apigen apidoc/json/domain inline_icons graphviz mermaid_diagrams demo_api python_apigen_demo python_apigen_generated/Dim python_apigen_generated/Dim.__init__-unbounded python_apigen_generated/Dim.__init__-size python_apigen_generated/Dim.__init__-exclusive_max python_apigen_generated/Dim.__init__-inclusive_max python_apigen_generated/Dim.exclusive_max python_apigen_generated/Dim.inclusive_min python_apigen_generated/Dim.label python_apigen_generated/Dim.size python_apigen_generated/DimExpression python_apigen_generated/DimExpression.__getitem__ python_apigen_generated/DimExpression.diagonal python_apigen_generated/DimExpression.label python_apigen_generated/DimExpression.translate_to python_apigen_generated/DimExpression.vindex python_apigen_generated/IndexDomain python_apigen_generated/IndexDomain.__init__-components python_apigen_generated/IndexDomain.__init__-dimensions python_apigen_generated/IndexDomain.__init__-json python_apigen_generated/IndexDomain.__getitem__-identifier python_apigen_generated/IndexDomain.__getitem__-selection python_apigen_generated/IndexDomain.__getitem__-domain python_apigen_generated/IndexDomain.__getitem__-expr python_apigen_generated/IndexDomain.__getitem__-transform python_apigen_generated/IndexDomain.to_json python_apigen_generated/IndexDomain.exclusive_max python_apigen_generated/IndexDomain.inclusive_min python_apigen_generated/IndexDomain.labels python_apigen_generated/IndexDomain.origin python_apigen_generated/IndexDomain.rank python_apigen_generated/IndexDomain.shape python_apigen_generated/IndexDomain.size python_apigen_generated/DimensionSelection python_apigen_generated/DimensionSelection.foo python_apigen_generated/bar python_apigen_generated/VeryLongClassNameForTestingOutWordWrapping python_apigen_generated/VeryLongClassNameForTestingOutWordWrapping.very_long_method_name_for_testing_out_word_wrapper python_apigen_generated/Foo python_apigen_generated/Foo.bar python_apigen_generated/FooSubclass python_apigen_generated/FooSubclass.baz python_apigen_generated/FooSubclass.overloaded_method cpp_apigen_demo cpp_apigen_generated/cpp_apigen_demo.IndexInterval cpp_apigen_generated/cpp_apigen_demo.IndexInterval.IndexInterval cpp_apigen_generated/cpp_apigen_demo.IndexInterval.operator-shift_left cpp_apigen_generated/cpp_apigen_demo.IndexInterval.lower cpp_apigen_generated/cpp_apigen_demo.IndexInterval.upper cpp_apigen_generated/cpp_apigen_demo.Union cpp_apigen_generated/cpp_apigen_demo.DataOrder cpp_apigen_generated/cpp_apigen_demo.operator-shift_left cpp_apigen_generated/cpp_apigen_demo.Array cpp_apigen_generated/cpp_apigen_demo.Array.Array-data-shape cpp_apigen_generated/cpp_apigen_demo.Array.Array-convert cpp_apigen_generated/cpp_apigen_demo.Array.data cpp_apigen_generated/cpp_apigen_demo.Array.shape cpp_apigen_generated/cpp_apigen_demo.Array.order cpp_apigen_generated/cpp_apigen_demo.Array.operator-subscript specimen rst_basics rst-cheatsheet/rst-cheatsheet additional_samples subpage1 subpage1subpage1 subpage1subpage2 subpage2 } /home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.3/docs/mermaid_diagrams.rst:63: WARNING: unknown node type: <mermaid_node: <literal...>>
failed

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 347, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 308, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 377, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.8/site-packages/sphinx/util/display.py", line 85, in wrapper
    return f(*args, **kwargs)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/manpage.py", line 101, in write
    docwriter.write(largetree, destination)
  File "/usr/lib/python3.8/site-packages/docutils/writers/__init__.py", line 77, in write
    self.translate()
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 34, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  [Previous line repeated 7 more times]
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/usr/lib/python3.8/site-packages/sphinx/util/docutils.py", line 588, in dispatch_departure
    super().dispatch_departure(node)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2018, in dispatch_departure
    return method(node)
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2040, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: mermaid_node

Exception occurred:
  File "/usr/lib/python3.8/site-packages/docutils/nodes.py", line 2040, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: mermaid_node
The full traceback has been saved in /tmp/sphinx-err-5x9hwfei.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!

@2bndy5
Copy link
Collaborator

2bndy5 commented Apr 23, 2023

If I remove all mermaid diagrams from the docs' src, I still run into problems inherent in the docutils.writers.manpage module... Adding manpage support doesn't seem to be a trivial request.

  File "path\to\.env\Lib\site-packages\docutils\writers\manpage.py", line 637, in depart_entry
    self._active_table.append_cell(self.body[start:])
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'append_cell'

@2bndy5 2bndy5 changed the title 0.11.3: sphinx-immaterial documentation build fails documentation build fails with manpage sphinx builder Apr 23, 2023
@kloczek
Copy link
Author

kloczek commented Oct 17, 2023

gentle ping .. any update? 🤔

@2bndy5
Copy link
Collaborator

2bndy5 commented Oct 17, 2023

Sorry there are no current plans to support the manage builder, and it clearly isn't a simple patch...

@kloczek
Copy link
Author

kloczek commented Oct 17, 2023

Looking on sphinx output seems like this issue has nothing to do with man page format because html rendering fails as well

[tkloczko@pers-jacek sphinx-immaterial-0.11.7]$ PYTHONPATH=$PWD /usr/bin/sphinx-build -n -T -b html docs build/sphinx/html
Running Sphinx v7.1.2
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
loading intersphinx inventory from https://myst-parser.readthedocs.io/en/latest/objects.inv...
[1/2] Loading JSON schema: apidoc/json/index_transform_schema.yml
[2/2] Loading JSON schema: apidoc/json/inheritance_schema.yml
Parsed C++ input in 0.00634 seconds
Found 19 C++ declarations
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'attrs_inline', 'smartquotes', 'deflist', 'replacements', 'fieldlist', 'tasklist', 'strikethrough', 'substitution', 'attrs_block'}, disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={role: ...}, 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', enable_checkboxes=True, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 89 source files that are out of date
updating environment: [new config] 89 added, 0 changed, 0 removed
reading sources... [  2%] admonitions
Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 290, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(to_build,
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 310, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 417, in read
    self._read_serial(docnames)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 438, in _read_serial
    self.read_doc(docname)
  File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 494, in read_doc
    publisher.publish()
  File "/usr/lib/python3.8/site-packages/docutils/core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 104, in read
    self.parse()
  File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 80, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, 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 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, 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 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/domains/__init__.py", line 286, in run
    return super().run()
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/object_toc.py", line 262, in run
    nodes = orig_run(self)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/object_toc.py", line 206, in run
    nodes = orig_run(self)
  File "/usr/lib/python3.8/site-packages/sphinx/directives/__init__.py", line 266, in run
    nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
  File "/usr/lib/python3.8/site-packages/sphinx/util/nodes.py", line 327, in nested_parse_with_titles
    return state.nested_parse(content, content_offset, node, match_titles=1)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, 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 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 146, in run
    result = parse_generated_content(self.state, params.result, documenter)
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 89, in parse_generated_content
    nested_parse_with_titles(state, content, node)
  File "/usr/lib/python3.8/site-packages/sphinx/util/nodes.py", line 327, in nested_parse_with_titles
    return state.nested_parse(content, content_offset, node, match_titles=1)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, 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 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/domains/__init__.py", line 286, in run
    return super().run()
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/object_toc.py", line 262, in run
    nodes = orig_run(self)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/object_toc.py", line 206, in run
    nodes = orig_run(self)
  File "/usr/lib/python3.8/site-packages/sphinx/directives/__init__.py", line 266, in run
    nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
  File "/usr/lib/python3.8/site-packages/sphinx/util/nodes.py", line 327, in nested_parse_with_titles
    return state.nested_parse(content, content_offset, node, match_titles=1)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, 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 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2357, in explicit_markup
    self.explicit_list(blank_finish)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2382, in explicit_list
    newline_offset, blank_finish = self.nested_list_parse(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 316, in nested_list_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2660, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 146, in run
    result = parse_generated_content(self.state, params.result, documenter)
  File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 89, in parse_generated_content
    nested_parse_with_titles(state, content, node)
  File "/usr/lib/python3.8/site-packages/sphinx/util/nodes.py", line 327, in nested_parse_with_titles
    return state.nested_parse(content, content_offset, node, match_titles=1)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 279, 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 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3.8/site-packages/sphinx/domains/__init__.py", line 286, in run
    return super().run()
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/object_toc.py", line 262, in run
    nodes = orig_run(self)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/object_toc.py", line 206, in run
    nodes = orig_run(self)
  File "/usr/lib/python3.8/site-packages/sphinx/directives/__init__.py", line 237, in run
    name = self.handle_signature(sig, signode)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/attribute_style.py", line 20, in handle_signature
    signode += sphinx.domains.python._parse_annotation(typ, self.env)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/type_annotation_transforms.py", line 265, in _parse_annotation
    tree = ast.fix_missing_locations(transformer.visit(tree))
  File "/usr/lib64/python3.8/ast.py", line 371, in visit
    return visitor(node)
  File "/usr/lib64/python3.8/ast.py", line 447, in generic_visit
    value = self.visit(value)
  File "/usr/lib64/python3.8/ast.py", line 371, in visit
    return visitor(node)
  File "/usr/lib64/python3.8/ast.py", line 456, in generic_visit
    new_node = self.visit(old_value)
  File "/usr/lib64/python3.8/ast.py", line 371, in visit
    return visitor(node)
  File "/usr/lib64/python3.8/ast.py", line 456, in generic_visit
    new_node = self.visit(old_value)
  File "/usr/lib64/python3.8/ast.py", line 371, in visit
    return visitor(node)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/type_annotation_transforms.py", line 247, in visit_Subscript
    return self._transform_subscript_pep604(node)[0]
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/type_annotation_transforms.py", line 220, in _transform_subscript_pep604
    id_str = _get_ast_dotted_name(value)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/type_annotation_transforms.py", line 115, in _get_ast_dotted_name
    parent = _get_ast_dotted_name(cast(Union[ast.Name, ast.Attribute], node.value))
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/type_annotation_transforms.py", line 115, in _get_ast_dotted_name
    parent = _get_ast_dotted_name(cast(Union[ast.Name, ast.Attribute], node.value))
AttributeError: 'NoneType' object has no attribute 'value'

Exception occurred:
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-immaterial-0.11.7/sphinx_immaterial/apidoc/python/type_annotation_transforms.py", line 115, in _get_ast_dotted_name
    parent = _get_ast_dotted_name(cast(Union[ast.Name, ast.Attribute], node.value))
AttributeError: 'NoneType' object has no attribute 'value'
The full traceback has been saved in /tmp/sphinx-err-9ir5eb3y.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!

@2bndy5
Copy link
Collaborator

2bndy5 commented Oct 17, 2023

The original error (shown on OP) indicated that it was related to the manpage builder.

Can you submit a zip file that can reproduce this?

@kloczek
Copy link
Author

kloczek commented Oct 18, 2023

Hmm .. what kind of zip file? 🤔
List of modules Installed in build env is like in ticket #299

@2bndy5
Copy link
Collaborator

2bndy5 commented Oct 18, 2023 •
edited

Given the error (in latest sphinx output) failed to understand the parsed AST of the python API you are documenting, I'm more interested in seeing what python (or document) source is being used. The zip file would be a sample project that uses this theme in sphinx (much like a demo repo).

@2bndy5
Copy link
Collaborator

2bndy5 commented Oct 18, 2023

Did you change the documentation source since opening this ticket? I'm getting the feeling like this new error is a separate issue.

@kloczek
Copy link
Author

kloczek commented Oct 18, 2023

Did you change the documentation source since opening this ticket?

I'm packaging your module as rpm package and build process downloads automatically source tar ball from git tag.
So .. source code could change in meantime only if you moved git tag.

@2bndy5
Copy link
Collaborator

2bndy5 commented Oct 18, 2023

Oh! I still think the new html builder error is a separate issue since there have been updates in sphinx, this theme, and python since you opened this ticket. However, I'm not sure why the AST error occurs in your env with the html builder; it might have something to do with using python 3.8. Currently, our CI uses all the latest dependencies (with python 3.11.5) to build our docs. Note: we are having problems building with python 3.11.5 on Windows (SSL related).

@kloczek
Copy link
Author

kloczek commented Oct 18, 2023

I should clearly mention as well that in mena time I've updated sphinx to 7.1.2 in my set od packaged python modules.
Sorry ..

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@2bndy5 @kloczek