do not install documentation files in buildroot

[xsuchy]

Fixes: #1389

[praiskup]

I'm neutral (or maybe a slight -1) to this, because "runtime" != "buildtime" (we should have a policy first), and it breaks me as the --shell user :shrug: I hate working in containers because these do not ship manual pages e.g.- but I see that we want to make those images as small as possible. With Mock we want to save the "time" rather than buildroot. Also, sometimes we do --postinstall to check everything installs fine (not sure potential doc-files conflicts are hidden by this change)

[xsuchy]

We have the policy: https://docs.fedoraproject.org/en-US/packaging-guidelines/#_documentation

Files located in %_pkgdocdir must not affect the runtime of the packaged software. The software must function properly and with unchanged functionality if those files are modified, removed or not installed at all.

[praiskup]

I mean that the build time of Foo can (in theory) depend on docs from BuildRequires: Bar (dunno, some build time or installation decisions need to be done?). We should directly say in policy that documentation files are not installed at package build time, so the build-time scripting should not depend on others' docs files.

[xsuchy]

During buildtime of FOO when it install the build dependency BAR then it is runtime for BAR.

[praiskup]

From the docs again to illustrate my point:

Files located in %_pkgdocdir must not affect the runtime of the packaged software.

When we package the software (my interpretation is that we mean Foo here, not the whole Fedora package set), we must make sure that the software (Foo) works even if the corresponding %doc files are not installed (note the somewhat unfortunate or intentional? %_pkgdocdir in the wording, which is just a subset of all the shipped package's %doc files, but also note that this dir is a package-specific directory).

During buildtime of FOO when it install the build dependency BAR then it is runtime for BAR.

Yes, and the Bar as the software is OK as well (as the SW works fine). Just the build-time of Foo (which is OK as well) might newly get affected.

[hroncok]

Some Python packages build documentation and they use documentation of other Python packages to generate proper links. Fox example:

$ repoquery -q --repo=rawhide-source --whatrequires python3-docs | pkgname
pychess
python-crcmod
python-cysignals
python-drgn
python-fixit
python-flask-babel
python-furo
python-gmpy2
python-jupyter-core
python-latexcodec
python-memray
python-nbdime
python-networkx
python-opentracing
python-patsy
python-pybtex
python-pybtex-docutils
python-pypdf
python-qpageview
python-sphinx-basic-ng
python-sphinxcontrib-bibtex
python-subliminal
python-trailrunner
python-usort
python-zope-event
python-zope-i18nmessageid
python-zope-interface
python-zope-testrunner
tbb

[Conan-Kudo]

This is probably going to be a problem, since this filters out all docdir files and package builds can and do chain on doc files when building documentation.

[voxik]

I am using Mock to test RPM installation. Not installing documentation would possibly result in different experience then regular users have.

[xsuchy]

The example from @hroncok is good enough for me to scratch this idea. I am going to close this PR. Still, if you have use cases that would be broken by this, you can write it here - I'd love to read about it.

[cgwalters]

Bigger picture I think we should be moving RPM builds into proper podman/Kube containers, not where mock is a custom container runtime and buildroot construction tool itself.

And if we do that as noted by people elsewhere it raises the obvious problem that the default quay.io/fedora/fedora:40 image does currently drop documentation. So we are inconsistent on this and I think the resolution is probably to add docs to that base image.