Build doxygen and sphinx (read-the-docs style) docs using cmake -D{project}_BUILD_DOCUMENTATION #14
Conversation
cmake/FindSphinx.cmake
Outdated
There was a problem hiding this comment.
Is this file ever used? It doesn't look like it.
There was a problem hiding this comment.
No, it isn't. I'll remove it if you're content with the "hard-coded" sphinx exe name.
Originally, I would have liked to install the sphinx dependency with poetry during the configuration phase, then call FindSphinx.cmake to grab the executable's name, then use that in the target command. Alas, such a workflow doesn't run.
docs/CMakeLists.txt
Outdated
| MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN} | ||
| COMMENT "Generating docs") | ||
|
|
||
| add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE}) |
There was a problem hiding this comment.
This target name needs to be project-specific (otherwise it will conflict with submodules that also create a doxygen target).
docs/CMakeLists.txt
Outdated
| # Note that "poetry run" during CMake's build phase does not activate an environment installed | ||
| # during CMake's configuration phase! | ||
|
|
||
| add_custom_target(Sphinx ALL |
There was a problem hiding this comment.
Needs project-specific target name (see previous comment).
pyproject.toml
Outdated
There was a problem hiding this comment.
If we are adding a python dependency (which I think we want/need to), we should consider how much to utilize it? Should we constrain it just to cases where "BUILD_DOCUMENTATION" is set? or do we want to leverage it for other things too?
- doit for task automation (could potentially replace some of our CMake scripts)
- regression testing framework?
- others?
There was a problem hiding this comment.
Shall I put these use cases under Issues so we don't lose them?
Description
Add support files for documentation scaffolding, and a CMake workflow that both checks for doxygen comments and converts them into web docs. (Any client of this workflow will still have to customize the ReStructuredText files.)
Author Progress Checklist:
Reviewer Checklist: