Fmt: Use sphinx and breathe from the system to build documentation

[daveisfera]

I'm trying to build the documentation as part of packaging for Fedora, but sphinx and breathe are pulled from github instead of using the system versions. Could this be fixed so the sphinx and breathe from the system are used all the time or at least when available?

For reference, the failed build can be found here.

[vitaut]

Unfortunately using system Sphinx and Breathe most definitely won't work unless very specific versions are installed. As for the error, it seems to be caused by inability to fetch dependencies via the git protocol. If this is the case https://github.com/fmtlib/fmt/commit/02553d13a0242809fbe54f1d123f0e44eec70f2e should fix it.

[daveisfera]

It still fails with that change ( https://koji.fedoraproject.org/koji/taskinfo?taskID=17110916 ).

Fedora Rawhide (26) have sphinx 1.4.9 and breathe 4.4.0. Are those not new enough to build the documentation?

[AdamWill]

"As for the error, it seems to be caused by inability to fetch dependencies via the git protocol."

No, it's failing because Fedora package builds are run without any network access, by policy. This is fairly common for distributions, which are very sceptical of build processes that just go out and gather crap from the internet; it doesn't make for very reproducible build processes, to say the least.

[vitaut]

Thanks for clarification, @AdamWill. This makes a lot of sense.

@daveisfera, I recommend using one of the packages with generated documentation such as fmt-3.0.1 then. C++ support in Sphinx has been under heavy development and I don't know if the documentation will be generated properly with sphinx 1.4.9 and breathe 4.4.0 (and I don't have time to investigate it right now).

[daveisfera]

I patched out the virtualenv stuff so the system versions of sphinx and breathe would be used. It built and it looked correct to me, but when I build without network access the call to doxygen still fails. Any ideas?

[vitaut]

The log shows that there was a segfault in doxygen:

subprocess.CalledProcessError: Command '['doxygen', '-']' returned non-zero exit status -11

I recommend submitting a bug report.

[daveisfera]

I was trying to make a minimal reproducer to submit a bug to doxygen but it's worked fine without network access in all of my tests. Also, several other Fedora packages use doxygen without issue (here are a few examples), so it appears that this is something specific to how building the documentation for fmt is using doxygen.

I noticed that fmt runs it with - to read from stdout and then pipes in parameters. I'm not all that familiar with doxygen, but could doing that instead of using a config file be causing the problem?

[vitaut]

I'm not all that familiar with doxygen, but could doing that instead of using a config file be causing the problem?

Could be. I also saw multiple bugs related to XML generation in doxygen in the past (but none of those was causing a crash).

Can you reproduce the crash when building full fmt docs? If yes, then I don't think you need to come up with a minimal reproducer. The library is small enough for the doxygen devs to be able to reproduce the issue in seconds.

[daveisfera]

The issue with doxygen has been resolved, so for Fedora packaging the docs are built from source using the system executables. Thanks for the help and making this an option or at least making it so it's not too hard for me to patch out the download would be great.
https://koji.fedoraproject.org/koji/buildinfo?buildID=829945

[vitaut]

Thanks for the update, @daveisfera, and, as always, for your work on packaging the library for Fedora.

Thanks for the help and making this an option or at least making it so it's not too hard for me to patch out the download would be great.

OK, I'll reopen this issue and will add an option. Can't promise that it will happen any time soon though, because I'm focused on the standards proposal.