[FEATURE REQUEST] sphinx-markdown-builder does not parse breathe directives

[ShawnHymel]

My goal is to go C++ source > doxygen > breathe > sphinx (with sphinx-markdown-builder) to produce markdown output. I am trying to run sphinx-markdown-builder with rst files containing breathe directives. For example, here is my index.rst:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   
.. doxygenclass:: cat
    :members:

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`

When I run sphinx, I get the following error:

/app/src/cat-test/doc/sphinx/source/index.rst:10: WARNING: unknown node type: <desc_signature_line: <target "classcat"...><desc_sig_keyword...><desc_sig_spa ...>

Exception occurred:
  File "/usr/local/lib/python3.8/dist-packages/sphinx_markdown_builder/contexts.py", line 339, in make
    assert len(content) > 0, "Empty title"
AssertionError: Empty title
The full traceback has been saved in /tmp/sphinx-err-psf6v4uh.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!

The output of /tmp/sphinx-err-psf6v4uh.log is the following:

# Platform:         linux; (Linux-5.15.49-linuxkit-aarch64-with-glibc2.29)
# Sphinx version:   7.1.2
# Python version:   3.8.10 (CPython)
# Docutils version: 0.20.1
# Jinja2 version:   3.1.4
# Pygments version: 2.18.0

# Last messages:
#   checking consistency...
#   done
#   preparing documents...
#   done
#   copying assets...
#   done

#   writing output... [100%]
#   index
#   

# Loaded extensions:
#   sphinx.ext.mathjax (7.1.2)
#   alabaster (0.7.13)
#   sphinxcontrib.applehelp (1.0.4)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.1)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   breathe (4.35.0)
#   sphinx_markdown_builder (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/usr/local/lib/python3.8/dist-packages/sphinx/cmd/build.py", line 290, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/local/lib/python3.8/dist-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(to_build,
  File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 567, in write
    self._write_serial(sorted(docnames))
  File "/usr/local/lib/python3.8/dist-packages/sphinx/builders/__init__.py", line 577, in _write_serial
    self.write_doc(docname, doctree)
  File "/usr/local/lib/python3.8/dist-packages/sphinx_markdown_builder/builder.py", line 90, in write_doc
    self.writer.write(doctree, destination)
  File "/usr/local/lib/python3.8/dist-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/usr/local/lib/python3.8/dist-packages/sphinx_markdown_builder/writer.py", line 50, in translate
    self.document.walkabout(visitor)
  File "/usr/local/lib/python3.8/dist-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/local/lib/python3.8/dist-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/local/lib/python3.8/dist-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/usr/local/lib/python3.8/dist-packages/sphinx/util/docutils.py", line 589, in dispatch_departure
    method(node)
  File "/usr/local/lib/python3.8/dist-packages/sphinx_markdown_builder/translator.py", line 168, in _pop_context
    ctx.add(last_ctx.make(), last_ctx.params.prefix_eol, last_ctx.params.suffix_eol)
  File "/usr/local/lib/python3.8/dist-packages/sphinx_markdown_builder/contexts.py", line 339, in make
    assert len(content) > 0, "Empty title"
AssertionError: Empty title

Any help on getting these directives to work would be appreciated!

[ShawnHymel]

Here is a simple project to replicate the issue.

Dependencies

doxygen==1.8.17
breathe==4.35.0
sphinx==7.1.2
sphinx-markdown-builder==0.6.6

Directory structure

cat-test/
|_ doc/
|   |_ doxygen/
|   |_ sphinx/
|       |_ build/
|       |_ source/
|           |_ _static/
|               (empty)
|           |_ index.rst
|_ src/
|   |_ cat.cpp
|_ conf.py
|_ Doxyfile

File contents

doc/sphinx/index.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`

Classes
-------
.. doxygenclass:: Cat
    :members:

src/cat.cpp

#include <iostream>

/**
 * A cute cat.
 */
class Cat {
public:
    Cat() {}

    /**
     * Pet the cat to make it purr.
     */
    void pet() {
        std::cout << "purr" << std::endl;
    }
};

int main() {
    Cat cat;
    cat.pet();

    return 0;
}

conf.py

project = 'My Cat Project'
copyright = '2024, Me'
author = 'Me'

extensions = [
    "breathe",
    "sphinx_markdown_builder"
]

templates_path = ["doc/sphinx/source/_templates"]
exclude_patterns = []

html_theme = 'alabaster'
html_static_path = ["doc/sphinx/source/_static"]

# Breathe Configuration
breathe_default_project = "MyCatProject"

Doxyfile

Generated with doxygen -g, but the following settings were changed:

...
PROJECT_NAME           = "My Cat Project"
...
OUTPUT_DIRECTORY       = doc/
...
INPUT                  = src/
...
GENERATE_HTML          = NO
...
GENERATE_LATEX         = NO
...
GENERATE_XML           = YES
...

Generate documentation

Generate XML by first running Doxygen:

doxygen

If you generate HTML, the breathe directives are picked up:

sphinx-build -b html doc/sphinx/source doc/sphinx/build -c . -Dbreathe_projects.MyCatProject=doc/doxygen/xml

However, when you try to generate markdown, the error in my first post shows up:

sphinx-build -M markdown doc/sphinx/source doc/sphinx/build -c . -Dbreathe_projects.MyCatProject=doc/doxygen/xml

...
copying assets... done
/app/src/cat-simple/doc/sphinx/source/index.rst:13: WARNING: unknown node type: <desc_signature_line: <target "classCat"...><desc_sig_keyword...><desc_sig_spa ...>

Exception occurred:
  File "/usr/local/lib/python3.8/dist-packages/sphinx_markdown_builder/contexts.py", line 339, in make
    assert len(content) > 0, "Empty title"
AssertionError: Empty title
The full traceback has been saved in /tmp/sphinx-err-3p1m3go9.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!

[liran-funaro]

Thanks for taking a time to report this issue. Please note that this is a feature request, not a bug. I don't have plans to implement new features at the time. But I will keep this issue open if I will have time for it in the future.