CMake: Support for XML documentation

[enetheru]

This PR extends #1499 - [DRAFT] Add CMake support for XML documentation
which follows #1374 - Allow submitting documentation to the Godot editor

This is also built upon #1670 - CMake: Support for using build_profile.json

This PR adds the equivalent functionality to the CMake build scripts. A summary below.

The SCons implementation adds a BUILDER to the env in tools/godotcpp.py:513

    # Builders
    env.Append(
        BUILDERS={
            "GodotCPPBindings": Builder(action=Action(scons_generate_bindings, "$GENCOMSTR"), emitter=scons_emit_files),
            "GodotCPPDocData": Builder(action=scons_generate_doc_source),
        }
    )

Which is then available for consumers to use, with the test example showing how at test/SConstruct:18

if env["target"] in ["editor", "template_debug"]:
    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
    sources.append(doc_data)

This CMake implementationa mirrors this with a function in cmake/python_callouts.cmake:109

function( generate_doc_source OUTPUT_PATH XML_SOURCES )
- - - <snip> - - - 

which calls the python function of the same name from doc_source_generator.py to create the cpp file at OUTPUT_PATH which can then be added to the sources list of the target. The test extension shows this starting in test/CMakeLists.txt:10

# Generate Doc Data
file( GLOB_RECURSE DOC_XML
    LIST_DIRECTORIES NO
    CONFIGURE_DEPENDS
    ${CMAKE_CURRENT_SOURCE_DIR}/doc_classes/*.xml )

set( DOC_DATA_SOURCE "${CMAKE_CURRENT_BINARY_DIR}/src/gen/doc_data.gen.cpp" )
generate_doc_source( "${DOC_DATA_SOURCE}" "${DOC_XML}" )

- - - <snip> - - - 

    # conditionally add doc data to compile output
    if( TARGET_ALIAS MATCHES "editor|template_debug" )
        target_sources( ${TARGET_NAME} PRIVATE "${DOC_DATA_SOURCE}" )
    endif(   )

[enetheru]

@dsnopek should I add the main function in the doc_source_generator.py to match the latest build_profile.py ?

[dsnopek]

Thanks! You can squash my commit in your commit, and I can close mine as superseded by yours.

should I add the main function in the doc_source_generator.py to match the latest build_profile.py ?

I think I'd actually prefer that we keep this code in binding_generator.py rather than creating a new doc_source_generator.py.

In my mind, build_profile.py is the exception, because it could be used by other bindings and we even discussed moving that functionality into Godot itself, so it makes sense for that to be a separate script with a main function.

However, the documentation stuff is squarely a part of godot-cpp, and I'd like to keep the number of Python scripts at the top-level to a minimum.

UPDATE: I changed my mind on this bit - see comment below.

[dsnopek]

I think I'd actually prefer that we keep this code in binding_generator.py rather than creating a new doc_source_generator.py.

In my mind, build_profile.py is the exception, because it could be used by other bindings and we even discussed moving that functionality into Godot itself, so it makes sense for that to be a separate script with a main function.

However, the documentation stuff is squarely a part of godot-cpp, and I'd like to keep the number of Python scripts at the top-level to a minimum.

Er, nevermind, thinking about this a little more, I think it's fine as a separate script. I don't want to end up with too many scripts at the top-level, but this is distinct enough from everything else binding_generator.py is doing, let's just leave it separate.

However, to answer the original questsion: no, I don't think doc_source_generator.py needs a main function. :-)

[dsnopek]

I just tried this with the test project and it worked great!

Skimming the code, that looks good to me too.

I think the only things this PR needs is:

1. Squash my commit and your commit like I mentioned above (you can list me as Co-authored-by: in the commit if you want, but my contribution is pretty small, I don't mind if it's omitted)
2. Rebase on master, since I just merged PR #1670