Sphinx warnings by default now cause doc build to fail #1344
Conversation
* Together with building the docs in the CI (AcademySoftwareFoundation#1339) this means that issues with the documentation will cause the CI checks to fail * All doxygen-annotated class/function comments must now be warning-free. This PR fixes a warning in openexr_context.h by adding missing parameter descriptions. Signed-off-by: Cary Phillips <cary@ilm.com>
|
I do wonder if we should enhance the "building" documentation. I know Sphinx is easy to install with pip (so I think we should mention that), but I wasn't sure about doxygen. I went and read these instructions https://www.doxygen.nl/manual/install.html and it gave me pause ~ basically, I think maybe we should link to the doxygen install documentation, and call out that just the base installer is required, there's no need to chase down graphviz or other optional components. At least I hope that's what we can call out :) My gut feeling is that in general we can count on doxygen being present at well managed sites, but not for example, at my house. |
|
Good suggestion, I added some references #1346. The doxygen instructions are confusing, because it starts right in with building from source, which is hopefully rarely necessary. But note that this PR just means that syntax errors in documentation will cause a failure. Missing the doxygen/sphinx installation would have already caused a failure, provided you're building the documentation, which is off by default. |
…reFoundation#1344) * Together with building the docs in the CI (AcademySoftwareFoundation#1339) this means that issues with the documentation will cause the CI checks to fail * All doxygen-annotated class/function comments must now be warning-free. This PR fixes a warning in openexr_context.h by adding missing parameter descriptions. Signed-off-by: Cary Phillips <cary@ilm.com>
* Together with building the docs in the CI (#1339) this means that issues with the documentation will cause the CI checks to fail * All doxygen-annotated class/function comments must now be warning-free. This PR fixes a warning in openexr_context.h by adding missing parameter descriptions. Signed-off-by: Cary Phillips <cary@ilm.com>
Together with building the docs in the CI (Build docs in CI, and rename DOCS CMake config variable to BUILD_DOCS #1339) this means that issues with the documentation will cause the CI checks to fail
All doxygen-annotated class/function comments must now be warning-free. This PR fixes a warning in openexr_context.h by adding missing parameter descriptions.