Add doxygen target using cmake-generated doxyfile #4700
Conversation
|
Agree this is useful. We will merge after the release to avoid modifying CMakeLists.txt just ahead of a release. I assume you have found https://docs.qmcpack.org/doxygen/doxy/ , which is run nightly. A potentially slicker and longer term solution would be to have the doxygen pages included in our readthedocs builds of the manual, but this is much more work and may need some bridging software. |
|
@prckent , part of the reason I wanted this is that the website you referenced (https://docs.qmcpack.org/doxygen/doxy/) seems drastically out of date. And yes, an automated build included with the rtd would be amazing. |
|
Can you give an example of what is missing from the current doxygen created files so that I can check the regeneration? The website has a current date, so it is not that the whole regeneration is failing. |
The inheritance diagram for SPOSet contains derived classes such as |
|
Check now. git repo updating was broken. |
SPOSet looks Okay. |
doxygen/CMakeLists.txt
Outdated
| set(DOXYGEN_INTERACTIVE_SVG YES) | ||
| set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES) | ||
|
|
||
| doxygen_add_docs(qmcpack_doxygen ${PROJECT_SOURCE_DIR}/src |
There was a problem hiding this comment.
Prefer
doxygen_add_docs(qmcpack_doxygen ${PROJECT_SOURCE_DIR}/src)
else()
message(STATUS "The qmcpack_doxygen target for the QMCPACK developer/API documentation requires (1) doxygen and (2) dot from graphviz.")
endif()
There was a problem hiding this comment.
I added a message to similar effect
doxygen/CMakeLists.txt
Outdated
| find_package(Doxygen) | ||
| if(DOXYGEN_FOUND) | ||
| set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}") | ||
| set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${PROJECT_SOURCE_DIR}/README.md) |
There was a problem hiding this comment.
I suggest to remove this, since it gives a very strange first page.
Can you modify the config here so that it gives an accessible start page like https://docs.qmcpack.org/doxygen/doxy/index.html ?
The one produced by this PR has a long function(?) list before the classes and files browser.
There was a problem hiding this comment.
@prckent I believe the issue was with the navigation tree on the left. I like using the README since it gives links to all the relevant things on the web. I addressed the navigation tree issues (and in my opinion it's more useful than the tree in the current published version). Let me know what you think.
There was a problem hiding this comment.
Note that if you don't want to see the main page headings in the navigation, they can be removed with:
set(DOXYGEN_TOC_INCLUDE_HEADINGS 0)
|
I still have interest in this. Will certainly make cleaning up doxygen output locally more convenient. It really should be part of dev workflow to see if our doxygen output for new work looks good or not. |
|
@PhilipFackler Will you be able to come back to this? This looked to be mergable after fixing the first page (DOXYGEN_USE_MDFILE_AS_MAINPAGE) to be more sensible somehow. Can be a very simple .md of your own creation. |
|
(I expect we'll merge this after it has been run independently, after the QMCPACK workshop this week) |
Proposed changes
This is a pretty small change to add a generated doxygen target (so you can
make qmcpack_doxygenand it will put the results in the build tree). I left the old doxygen work untouched and simply added a CMakeLists.txt file to the doxygen directory. This could be further customized of course, but it provides an easy way for developers to look at an up-to-date doxygen site locally.What type(s) of changes does this code introduce?
Does this introduce a breaking change?
What systems has this change been tested on?
Ubuntu 22.04
Checklist