Closed Time0o closed 5 years ago
Hmm. Smells like a bug with breathe. Let's talk more here first though. Is there a public link you can give me to the code?
If not include the relevant sections of conf.py
(exhale_args
, breathe configurations) and in particular your doxygen configuration. If you're using an actual Doxyfile
, upload it to gist.github.com (since it's huge xD).
My project is located here: https://github.com/Time0o/TUD_computational_group_theory, the Doxyfile is located at doxygen/Doxyfile. The sphinx conf.py
is dynamically generated by CMake (which kind of sucks, I'll admit it), look at the toplevel CMakeLists.txt, line 133 following. Unfortunately I have just switched the hosted documentation to pure Doxygen, since it's basically empty anyways I'll try to host the exhale results at: https://time0o.github.io/TUD_computational_group_theory/ shortly.
Hey @Time0o I'm really confused about how your docs are setup. I don't get a conf.py
generated anywhere. I'm also not sure why you would want to generate one from CMake. Anyway I can't really help since I can't reproduce things. Right now exhale forces you to have Doxyfile
next to conf.py
, that will be relaxed in the future but to test exhale i would suggest you just do
# from repo root, just for testing
$ mkdir exhale_docs
$ cd exhale_docs
$ sphinx-quickstart
Then use the exhaleDoxygenStdin
approach. There's not really much of a reason for you to be configuring the Doxyfile
and a conf.py
for this project, it's not like those are changing right? You probably want something like (assuming for sphinx-quickstart
first question > Separate source and build directories (y/n) [n]:
you said n
):
import textwrap
extensions = ["breathe", "exhale"]
breathe_projects = {
"MPSoC Symmetry Reduction Library": "_doxygen/xml"
}
breathe_default_project = "MPSoC Symmetry Reduction Library"
exhale_args = {
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API",
"doxygenStripFromPath": "..",
"createTreeView": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": textwrap.dedent('''
INPUT = ../include ../src ../doxygen ../doxygen/dox
# CITE_BIB_FILES are just ../doxygen/bin/ ... ?
# any other custom stuffs you want
''')
}
The answer to "spearate source and build directories" matters because relative paths are relative to conf.py
. When you say no
, it'll be in exhale_docs/source/conf.py
so you need to adjust doxygenStripFromPath
and INPUT
etc.
Anyway that's just the test I did, and private members weren't showing up. I think if you can remove the CMake configure complexity you'll probably see different results. So if you like what you get out of that, then blow away your docs/
folder and do it slightly different:
[y]
to separate source and build directories. That'll give you a docs/build/html
in the end.docs/source/conf.py
, and exhale currently requires that you move doxygen/Doxyfile
to docs/source/Doxyfile
. Then also move the two folders in there to the source/
dir, and add them to exclude_patterns
so Sphinx ignores them.Hope this makes sense, i wanted to give you a thoughtful response but i have to run out the door x0. I think the problem you were encountering is from something going wrong in your configuration for Doxygen. Not really sure because I couldn't run a sample.
P.S. if you're using GitHub pages, you can get Travis CI to automatically update things. Tracking the generated docs files like you are right now in (from exhale or vanilla doxygen) is inadvisable...you're going to create a massive diff history on your repo like that over time, making it annoying to clone ;)
Thanks for the detailed response. I think you are right, my documentation build is very messy atm. It's good to know that this is not a general problem with exhale, I will try to clean things up in my project when I have the time and I assume the problem will just solve itself.
I'm not sure if this is an issue with breathe or exhale but by default private member classes (which are definitely not part of the API) are displayed in the API documentation, i.e. without enabling
:private-members:
. To me this seems to be a bug, is there currently a way to disable this behaviour?