From 93eaf73fb35b2690ebcbd439373ccdd19c7564a4 Mon Sep 17 00:00:00 2001 From: Porter Zach <76142641+p-zach@users.noreply.github.com> Date: Wed, 12 Mar 2025 16:32:33 -0400 Subject: [PATCH 1/3] Add how to generate docstrings --- python/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/python/README.md b/python/README.md index 5f7522920..e2f1a1f41 100644 --- a/python/README.md +++ b/python/README.md @@ -38,6 +38,15 @@ For instructions on updating the version of the [wrap library](https://github.co See Windows Installation in INSTALL.md in the root directory. +## Generate Docstrings + +The wrap library provides for building the Python wrapper with docstrings included, sourced from the C++ Doxygen comments. To build the Python wrapper with docstrings, follow these instructions: + +1. Change `GENERATE_XML` in `doc/Doxyfile.in` to `YES`. +2. Build GTSAM. This will compile the `doc/Doxyfile.in` into a `Doxyfile`. +3. From the project root directory, run `doxygen build//doc/Doxyfile`. This will generate the Doxygen XML documentation in `xml/`. +4. Build the Python wrapper with the CMake option `GTWRAP_ADD_DOCSTRINGS` enabled. + ## Unit Tests The Python toolbox also has a small set of unit tests located in the From 65ea0112c58552e7adc941a0cf769e250da4b388 Mon Sep 17 00:00:00 2001 From: Yashas Ambati Date: Thu, 27 Mar 2025 12:48:15 -0400 Subject: [PATCH 2/3] Add CMake flag for enabling doxygen XML generation --- doc/CMakeLists.txt | 7 +++++++ doc/Doxyfile.in | 2 +- python/README.md | 7 +++---- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 05e0a13ef..ba3d75e90 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -4,6 +4,7 @@ option(GTSAM_BUILD_DOCS "Enable/Disable building of doxygen doc # configure doxygen option(GTSAM_BUILD_DOC_HTML "Enable/Disable doxygen HTML output" ON) option(GTSAM_BUILD_DOC_LATEX "Enable/Disable doxygen LaTeX output" OFF) +option(GTSAM_GENERATE_DOC_XML "Enable/Disable doxygen XML output" OFF) # add a target to generate API documentation with Doxygen if (GTSAM_BUILD_DOCS) @@ -20,6 +21,12 @@ if (GTSAM_BUILD_DOCS) set(GTSAM_BUILD_DOC_LATEX_YN "NO") endif() + if (GTSAM_GENERATE_DOC_XML) + set(GTSAM_GENERATE_XML_YN "YES") + else() + set(GTSAM_GENERATE_XML_YN "NO") + endif() + # GTSAM core subfolders set(gtsam_doc_subdirs gtsam/base diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 0f789be66..3461127ae 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -2120,7 +2120,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = @GTSAM_GENERATE_XML_YN@ # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/python/README.md b/python/README.md index e2f1a1f41..4d195a821 100644 --- a/python/README.md +++ b/python/README.md @@ -42,10 +42,9 @@ See Windows Installation in INSTALL.md in the root directory. The wrap library provides for building the Python wrapper with docstrings included, sourced from the C++ Doxygen comments. To build the Python wrapper with docstrings, follow these instructions: -1. Change `GENERATE_XML` in `doc/Doxyfile.in` to `YES`. -2. Build GTSAM. This will compile the `doc/Doxyfile.in` into a `Doxyfile`. -3. From the project root directory, run `doxygen build//doc/Doxyfile`. This will generate the Doxygen XML documentation in `xml/`. -4. Build the Python wrapper with the CMake option `GTWRAP_ADD_DOCSTRINGS` enabled. +1. Build GTSAM with the flag `-DGTSAM_GENERATE_DOC_XML=1`. This will compile the `doc/Doxyfile.in` into a `Doxyfile` with `GENERATE_XML` set to `ON`. +2. From the project root directory, run `doxygen build//doc/Doxyfile`. This will generate the Doxygen XML documentation in `xml/`. +3. Build the Python wrapper with the CMake option `GTWRAP_ADD_DOCSTRINGS` enabled. ## Unit Tests From 2ea071dc913891408074f087c932e23260e6a395 Mon Sep 17 00:00:00 2001 From: Yashas Ambati Date: Thu, 3 Apr 2025 14:58:43 -0400 Subject: [PATCH 3/3] Comment for doxygen variables --- doc/CMakeLists.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index ba3d75e90..8d4692fdb 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -8,7 +8,8 @@ option(GTSAM_GENERATE_DOC_XML "Enable/Disable doxygen XML output" # add a target to generate API documentation with Doxygen if (GTSAM_BUILD_DOCS) - # Convert configuration to YES/NO variables + # The following if statements convert ON/OFF CMake flags to YES/NO variables + # since Doxygen expects YES/NO for boolean options. if (GTSAM_BUILD_DOC_HTML) set(GTSAM_BUILD_DOC_HTML_YN "YES") else()