Build documentation with hotdoc

[thiblahute]

This is the very basic stub to generate the documentation with the hotdoc C extension (requires llvm). Currently there is basically not doc string so the documentation is very sparse!

You can find the current output here: https://people.igalia.com/tsaunier/documentation/libwpe/c-index.html

Fixes #37

[aperezdc]

Looks good overall, but please check the comment.

[aperezdc]

It looks to me that it would be good to use find_program() to know whether the hotdoc tool is available before trying to use it.

[aperezdc]

Also, I would prefer that building the documentation is controlled by an option() variable, instead of automatically deciding whether it will be built depending on the availability of the hotdoc and its C extension. That means that, if the option to build the documentation is enabled, if the hotdoc program or its C extension are missing, configuring with CMake should fail instead of silently disabling the documentation (“Explicit is better than implicit”, after all 😉).

[thiblahute]

It looks to me that it would be good to use find_program() to know whether the hotdoc tool is available before trying to use it.

DONE, it sensibly enhance the debug message but considered it useless first, anyway if you prefer.

Also, I would prefer that building the documentation is controlled by an option() variable, instead of automatically deciding whether it will be built depending on the availability of the hotdoc and its C extension. That means that, if the option to build the documentation is enabled, if the hotdoc program or its C extension are missing, configuring with CMake should fail instead of silently disabling the documentation (“Explicit is better than implicit”, after all wink).

DONE.

[aperezdc]

Mmmh, is there something missing, like for example the configuration files for HotDoc? I tried applying the commit locally and all that HotDoc generates for me is an empty HTML 🤔

[thiblahute]

Mmmh, is there something missing, like for example the configuration files for HotDoc? I tried applying the commit locally and all that HotDoc generates for me is an empty HTML thinking

No it doesn't need a config file because I pass everything needed as arguments. Could you show me all the logs?

I just cloned and tried from a clean build on my build machine and everything works just fine here.

[aperezdc]

This is looking almost perfect, thanks for the update! Would you mind doing a coupl of changes more to ensure cross-compilation is handled as best as possible?

[aperezdc]

Could we call this BUILD_DOCS instead? It seems to be the name that most CMake projects use as a convetion, and some build systems automatically pass -DBUILD_DOCS= to CMake automatically (Buildroot, for example).

[tsaunier]

Done, I do not know anything about CMake and the conventions around it, thanks for letting me know! :-)

[aperezdc]

Checking the docs for find_program() I understand that the HAS_HOTDOC variable will be set to the full path of the program, when found. I think this would be nicer as follows:

    find_program(HOTDOC hotdoc)
    if (NOT HOTDOC)
        message(FATAL_ERROR "hotdoc not found!")
    endif()

    execute_process(
        COMMAND ${HOTDOC} --has-extension c-extension
        RESULT_VARIABLE HAS_HOTDOC_C_EXTENSION
    )
    # ...

Note how the ${HOTDOC} variable is used, this way the path detected by CMake is being used. This can be important (e.g. when cross-building) because the binary to run may not be the one in one of the locations from the PATH environment variable.

[tsaunier]

Done.

[aperezdc]

Please fix the indentation.

[tsaunier]

Done

[tsaunier]

Hope we are good now. Thanks for the review!

[aperezdc]

This looks all good now, thanks a lot for the effort @thiblahute! I am still having trouble to get the generated files to have any content at all, but I'll blame that in the Arch Linux package for HotDoc this time.

Nevertheless, before merging I would like to try using HotDoc with a Fedora chroot (is that the distro you use?) or at least a virtualenv to make sure that the problem is on my side, so please give me a couple of days before hitting the “Rebase and merge” button 😉

[thiblahute]

You should pip install installing required dependencies as described here: https://hotdoc.github.io/installing.html

I am using Fedora these days, but used to use Arch (a few month ago) and hotdoc was working well there.

[zdobersek]

Thanks for setting this up.

Do we want to build up more meaningful documentation in a separate branch, or just do it in master?

[aperezdc]

@thiblahute It's working here now as well 👍

@zdobersek I think we can merge this to have the documentation building, and incrementally add documentation in follow-up PRs. Documentation can be a good starting point for new contributors, so I think we can leave #37 open and marked as “good first bug” after this is merged (or add a new issue) to make people aware that the actual documentation is still missing.

Additionally, we can start asking in reviews for new PRs to have documentation for the public API, if they add to it. WDYT?

[zdobersek]

SGTM.