search

liran-funaro / sphinx-markdown-builder

A Sphinx extension to add markdown generation support.
https://pypi.org/project/sphinx-markdown-builder
MIT License
40 stars 16 forks source link

[BUG] `assert isinstance(ctx, FootNoteContext)` Fails #25

Open iguessthislldo opened 1 week ago

iguessthislldo commented 1 week ago

Describe the bug

The latest release (0.6.7) of the markdown builder throws an assertion in our project:

[app] emitting event: 'doctree-resolved'(<document: <section "android"...>>, 'devguide/building/android')
[app] emitting event: 'build-finished'(AssertionError(),)
Exception occurred while building, starting debugger:
Traceback (most recent call last):
... (Omitted Sphinx Frames)
File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/sphinx_markdown_builder/builder.py", line 91, in write_doc
    self.writer.write(doctree, destination)
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/sphinx_markdown_builder/writer.py", line 51, in translate
    self.document.walkabout(visitor)
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ^^^^^^^^^^^^^^^^^^^^^^^^
  [Previous line repeated 2 more times]
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/docutils/nodes.py", line 178, in walkabout
    visitor.dispatch_visit(self)
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/sphinx/util/docutils.py", line 723, in dispatch_visit
    method(node)
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/sphinx_markdown_builder/translator.py", line 761, in visit_label
    self.footnote_ctx.visit_label()  # workaround pylint: disable=no-member
    ^^^^^^^^^^^^^^^^^
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/sphinx_markdown_builder/translator.py", line 235, in __getattribute__
    return super().__getattribute__(item)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../OpenDDS/docs/.venv/lib/python3.12/site-packages/sphinx_markdown_builder/translator.py", line 742, in footnote_ctx
    assert isinstance(ctx, FootNoteContext)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError

In PDB, I can see what ctx is:

(Pdb) p ctx
<sphinx_markdown_builder.contexts.SubContext object at 0x7df0af2ad8e0>

After some poking around, it looks like it's happening here. These are tabs for selectively showing content like OS-specific instructions. If I take out all the .. tab directives in android.rst, it asserts on next the file with .. tab.

To Reproduce Steps to reproduce the behavior:

  1. Clone https://github.com/OpenDDS/OpenDDS
  2. Change the sphinx-markdown-builder line in docs/requirements.txt to 0.6.7
  3. In OpenDDS run ./docs/build.py markdown -d. This is a script I put together to make things easier for my colleagues so they don't have to create a virtual environment, run pip, etc. If you'd rather not run it, I think this should be the bare minimum to do the same thing:
    • pip install -r docs/requirements.txt
    • sphinx-build -M markdown docs docs/_build -vv --pdb

Expected behavior

0.6.6 prints warnings like the following and completes:

.../OpenDDS/docs/devguide/building/android.rst:150: WARNING: unknown node type: <label: <#text: 'Linux and macOS'>>

Environment (please complete the following information):

iguessthislldo commented 1 week ago

I should add that I'm not sure if sphinx-inline-tabs should be using the label node or not, assuming that's the issue, but other builtin builders like pdf and text don't have this problem.