Use CMake

[tdegeus]

I have a library that depends on a number of different libraries. I use CMake to find them, and I would like pybind11_mkdoc to do the same. How do I do that?

[cluttrdev]

Could you be more specific? From my perspective, the way you phrased it its not clear whether you want cmake to find pybind11_mkdoc or pybind11_mkdoc to find libraries?

[aloisklink]

If you're asking asking how to use CMake to pass all of the INCLUDE_DIRECTORIES of their library to pybind11_mkdoc (and run pybind11_mkdoc automatically), my solution is like follows:

find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
find_package(pybind11 CONFIG REQUIRED)

add_custom_command(
  OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/auto-generated/docstrings.h"
  COMMAND Python::Interpreter
  ARGS
    -m pybind11_mkdoc
    --output auto-generated/docstrings.h
    # TODO: there's a better way of doing this in CMake 3.27
    # see https://cmake.org/cmake/help/v3.27/manual/cmake-generator-expressions.7.html#whitespace-and-quoting
    "-I;$<JOIN:$<TARGET_PROPERTY:my_module,INCLUDE_DIRECTORIES>,;-I;>"
    "${CMAKE_CURRENT_SOURCE_DIR}/src/my_module_headers.hpp"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

python_add_library(my_module MODULE
  src/my_module.cpp auto-generated/docstrings.h
)
target_link_libraries(my_module PRIVATE pybind11::headers)

The key-bit is that we can use $<TARGET_PROPERTY:my_module,INCLUDE_DIRECTORIES> to get a list of all of the include directories for my_module.

This is pretty great if you're using scikit-build-core, as you can then run pybind11_mkdoc automatically whenever somebody installs your package (although it might have to wait until #32 gets merged)!

[leakec]

This looks great! I'm using something similar in a project:

function (pybind11_mkdoc)
    set(options)
    set(oneValueArgs OUTPUT)
    set(multiValueArgs TARGET_INCLUDES HEADERS)
    cmake_parse_arguments(PARSE_ARGV 0 arg
        "${options}" "${oneValueArgs}" "${multiValueArgs}"
    )

    # Get the module name 
    get_filename_component(module_name ${CMAKE_CURRENT_SOURCE_DIR} NAME)

    # Get the output header file name 
    set(header_name ${arg_OUTPUT})

    # Set the output header file location
    set(new_header ${CMAKE_BINARY_DIR}/include/${module_name}/${header_name})

    # Remove the header file from the list
    set(HEADERS "")
    # Run through all the other arguments.
    foreach(header ${arg_HEADERS})
        if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${header}")
            # If it exists with the given path on the source directory, then use that.
            list(APPEND HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/${header})
        else()
            # Otherwise, assume it is relative to the build's include directory.
            list(APPEND HEADERS ${CMAKE_BINARY_DIR}/include/${header})
        endif()
    endforeach()

    # Add a custom target using the header name
    add_custom_target(${header_name} ALL
        DEPENDS ${new_header}
    )

    # Run through all the target includes
    set(target_includes "")
    foreach(target ${arg_TARGET_INCLUDES})
        get_property(dark TARGET ${target} PROPERTY INTERFACE_INCLUDE_DIRECTORIES)
        foreach(dir ${dark})
            list(APPEND target_includes -I${dir})
        endforeach()
    endforeach()

    # Add a custom command for the full header file location that runs pybind11-mkdoc
    # We automatically include the source directory and build/include
    add_custom_command(
        OUTPUT ${new_header}
        COMMAND python -m pybind11_mkdoc -std=c++20 -DPYBIND11_MKDOC_SKIP -o ${new_header} ${target_includes} ${HEADERS}
        DEPENDS ${HEADERS}
    )
endfunction()

Some of this is obviously project specific. @aloisklink I like how you created the command and grabbed the headers; much more succinct and robust than what I did here. Having it in a function where you can parse the args is nice though, as it allows one to call it like this:

pybind11_mkdoc(OUTPUT output_doc.h
    HEADERS
     include/header_1.h
     include/header_2.h
    TARGET_INCLUDES Eigen3::Eigen some_other::target
)

[leakec]

Okay, I've combined things and have been using this with success on a large project for a little whlie now:

function (pybind11_mkdoc)
    set(options)
    set(oneValueArgs OUTPUT PYBIND11_MODULE)
    set(multiValueArgs TARGET_INCLUDES HEADERS)
    cmake_parse_arguments(PARSE_ARGV 0 arg
        "${options}" "${oneValueArgs}" "${multiValueArgs}"
    )

    # Include directories for the pybind11 module
    set(prop "$<TARGET_PROPERTY:${arg_PYBIND11_MODULE},INCLUDE_DIRECTORIES>")

    # Remove the header file from the list
    set(HEADERS "")
    # Run through all the other arguments.
    foreach(header ${arg_HEADERS})
        if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${header}")
            # If it exists with the given path on the source directory, then use that.
            list(APPEND HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/${header})
        else()
            # Otherwise, assume it is an absolute path
            list(APPEND HEADERS ${header})
        endif()
    endforeach()

    # Add a custom command for the full header file location that runs pybind11-mkdoc
    # We automatically include the source directory and build/include
    add_custom_command(
        OUTPUT ${arg_OUTPUT}
        COMMAND Python::Interpreter -m pybind11_mkdoc -o ${arg_OUTPUT} "$<$<BOOL:${prop}>:-I$<JOIN:${prop},;-I>>" ${HEADERS}
        DEPENDS ${HEADERS}
        COMMAND_EXPAND_LISTS
    )

    # Add the current binary directory to the pybind11 module so it can be included easily
    target_include_directories(${arg_PYBIND11_MODULE} PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
endfunction()

It is used like this:

pybind11_add_module(my_pybind11_module src/my_pybind11_module.cc my_byind11_module_doc.h)
pybind11_mkdoc(
    OUTPUT my_byind11_module_doc.h 
    PYBIND11_MODULE my_pybind11_module
    HEADERS 
        include/my_header_1.h
        /absolute/path/to/header.h
)

The pybind11_add_module command must come first. Then, one can call the pybind11_mkdoc. This creates a header with the proper includes based on parsing all headers gvein in HEADERS. It generates the OUTPUT into the current binary directory, which is automatically added as an include directory for the pybind11 module. The headers can be absolute paths or relative to the current source directory. One thing I think should be added is a string argument that is passed verbatim to pybind11_mkdoc, this would essentially be a catch-all for any other arugments that users need passed, e.g., -std=c++20. I'll leave this here for a bit for feedback before implementing it.

[leakec]

@henryiii This can be closed now that #51 is merged