diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 05e0a13ef..8d4692fdb 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -4,10 +4,12 @@ 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) - # 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() @@ -20,6 +22,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 5f7522920..4d195a821 100644 --- a/python/README.md +++ b/python/README.md @@ -38,6 +38,14 @@ 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. 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 The Python toolbox also has a small set of unit tests located in the