phniix
commented
5 years ago There is a fair bit going on in the documentation generation, so here are my ideas on a piecewise transition from Python to CMake.
I think the juice is worth the squeeze. I'd love to hear your thoughts. It would be great to find out if some of these ideas resonate with you.
Finding Doxygen and requiring dot
CMake provides a Doxygen find package module, which dates back to the minimum CMake version requirements for this project. 3.1.1 - https://github.com/Kitware/CMake/blob/v3.1.1/Modules/FindDoxygen.cmake 2.8.8 - https://cmake.org/cmake/help/v2.8.8/cmake.html#module:FindDoxygen
The Doxygen find_package() module cleverly enforces the default need for dot to be available on the system. As a result, we can utilise this CMake package to trim down the code in CMakeLists.txt, as well as the code in generateDocs.py.
Doxyfile.in would need a small tweak to account for the variable name change for tag DOT_PATH.
Python subprocess for doxygen command
We can add additional commands to the custom target 'documentation' in CMakeLists.txt. This will then remove the need to have generateDocs.py execute doxygen as a subprocess.
An added benefit of this approach is that warnings and errors encountered by doxygen will be displayed as part of the build process. Currently, running the doxygen Doxyfile manually will highlight warnings and errors (some of which are false positives!), however these are lost in the generateDocs.py execution of the implementation.
Python file copy operations
There are a lot of file copy operations which occur in order to conform the source file layout to the expectation set for the INPUT tag in Doxyfile.in.
As an aside: There may be a discussion on how this may be better managed so as to reduce inode count.. such a conversation would of course be welcome, and devops teams are encouraged to share their experiences and thoughts!
The module flattening and file copy operations in generateDocs.py are able to be transposed from Python to CMake. File operations in Python that can also be moved into CMake as additional commands to the custom target 'documentation'. We can also approach removing some file copy operations if we take a slightly different approach on how we execute the doxygen build command.
spitzak
jtran56
usmanredsoft-zz
sunyab
Description of Issue
The documentation generation process has a dependency on Python. As part of the build process, it would be nice if we could have a cross-platform solution that doesn't depend on Python being available on a host build system.
Recently, a convo in issue #605 discussed the build time Python dependency for copying header files. The general feeling that we flowed towards was removing all Python build time dependencies, unless specifically asking to build with Python support. As a result, the Python dependency on document generation was brought up, something I thought would be worthwhile pursuing here in this separately tracked issue.
We would like to discuss the transition of the current docgen code from Python to CMake.
Current Python docgen code: https://github.com/PixarAnimationStudios/USD/blob/master/cmake/macros/generateDocs.py Current CMake docgen code utilising the above Python docgen code: https://github.com/PixarAnimationStudios/USD/blob/6c50b29bb76f0a7c176bae05668ab195520a019b/CMakeLists.txt#L70
From our convo on this topic in issue #605 , a question we did raise was: is the juice worth the squeeze ?
Steps to Reproduce
Make sure that the minimum requirements for document generation have been met by the build system you are on. See Optional Components - Documentation. These tools need to be on your PATH (*nix,darwin|win), or in your REGISTRY (win).
Generate build files from a build directory.
Build documentation
System Information (OS, Hardware)
Windows 10 Home - 10.0.17134 Build 17134 Visual Studio 2017 Community v15.8.8 - CL.exe (x64) 19.15.26732.1
USD dev branch. Commit SHA1: 79f095a
Package Versions
Doxygen 1.8.4, 1.8.6, 1.8.14 * (I did try this using v1.8.4 because that's the version reported in Doxyfile.in) Graphviz 2.38.0 Python 3.7.0 CMake 3.11.4 Boost 1.68 TBB 2018 U5
Build Flags
Command Log Dump
Build file generation.
Document Generation