ShawnHymel
commented
1 month ago 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
|_ DoxyfileFile 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:
doxygenIf 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/xmlHowever, 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
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:
When I run sphinx, I get the following error:
The output of /tmp/sphinx-err-psf6v4uh.log is the following:
Any help on getting these directives to work would be appreciated!