Manual pages can no longer be built during the build

[tomhughes]

Even with #301 there are still problems building the manual pages as part of distribution packaging with the new build system.

The problem is that the new build system removes the build files after it creates the wheel, but running the make to build the manual pages needs to be able to import osmium.

Basically the package build for Fedora looked like this:

%build
%pyproject_wheel
PYTHONPATH=$PWD/build/lib.%{python3_platform}-cpython-%{python3_version_nodots} %make_build -C docs man


%install
%pyproject_install
%pyproject_save_files osmium
mkdir -p %{buildroot}%{_mandir}/man1
install -p -m644 docs/man/*.1 %{buildroot}%{_mandir}/man1

where the second step in %build is forcing the path to make the newly built osmium module available but that no long works as creating the wheel now cleans those up.

My workaround is to build the documentation as part of the install after the wheel has been unpacked again:

%build
%pyproject_wheel


%install
%pyproject_install
%pyproject_save_files osmium
PYTHONPATH=%{buildroot}%{python3_sitearch} %make_build -C docs man
mkdir -p %{buildroot}%{_mandir}/man1
install -p -m644 docs/man/*.1 %{buildroot}%{_mandir}/man1

but it's a bit naughty to be doing part of the build in the install section :-(

[lonvia]

Relying on the build artifacts is a bit naughty as well. And I've learned the hard way that it is going to cause issues once you start packaging for the free-threaded Python variants.

We could generate the man pages for the sdist package. But that wouldn't help you either as far as I can see because the source package or its content don't stay around either.

So I guess the still naughty but most pragmatic solution for this is to simply commit the generated man pages into git so that they are part of the release tarball and packagers don't need to generate anything at all.

[tomhughes]

I'm not sure what exactly constitutes the sdist package but if that means including them in the built wheel then that is probably fine.

Basically the %pyproject_wheel macro runs pip wheel ... to build the wheel then %pyproject_install unpacks that wheel into the build root directory using pip install --root %{buildroot} ... and the rpm is then built from the files in the build root so if that build/install script led to the man pages being installed in the build root then that would be fine.

[lonvia]

The sdist packages contain all sources to build the package, while the wheels only contain what is necessary for execution. There is no standard way of including man pages into wheels despite there being a discussion since 2015. I could include them as custom data in the wheel but then you'd still have to manually copy them to the final location. I've added the man pages to the git repo now, which is a little bit less work from my side.