Initial PoC for packaging with manpages

[harkabeeparolus]

Subject: Package wheels and sdists with manpages

[UPDATED]

Feature or Bugfix

• Feature

Purpose

• When installing Sphinx with pipx or pip, it could automatically make available the manpages for the script entrypoints
  (sphinx-build, sphinx-quickstart, sphinx-apidoc, sphinx-autogen).

  All that is necessary is that the wheel/sdist contains a "share/man/man1" folder with the manpages.

  Since Sphinx is packaged with flit, the intended way to install manpages is with the
  external data section.

Detail

• Currently I just modified the Makefile rule for make build.
  • It runs tox run -e manpages.
• I guess the GitHub "create-release.yml" workflow could regenerate the manpages and put them into the "data" directory so flit can pick them up.
• flit fails the build if the "data" dir is missing.
  • Currently I made an empty "data" directory (containing just a ".gitkeep" file) to ensure this never happens.

[AA-Turner]

I think this is best dealt with via a build script, though it would mean that the Git source and the sdist become desynchronised.

This would also need to be cross-platform, as I use Windows.

Please could you add an entry to CHANGES?

A

[harkabeeparolus]

I think this is best dealt with via a build script, though it would mean that the Git source and the sdist become desynchronised.

Yeah, it's not ideal. This is why I'm only making this PR a draft at this point. I know what I want the end result to be, just not how to make it work with your current CI/CD and packaging setup.

This would also need to be cross-platform, as I use Windows.

Fair! I just saw the Makefiles and re-used them.

Please could you add an entry to CHANGES?

Sure! I'll take a look later.

[harkabeeparolus]

On reflection I do not like that flit decided against having a declarative way of specifying data files. Seems to me that decision makes it tougher to write reliable build scripts and CI/CD pipelines. 😟

I think this is best dealt with via a build script, though it would mean that the Git source and the sdist become desynchronised.

What if we include a data directory in source control that is "empty" (just a .gitkeep file so Git will track it)?

• This ensures that flit never fails a build due to a missing data directory.
• The build scripts can then fill the data directory with manpages.
• There are no pre-rendered manpages in source control that go out of sync.

[harkabeeparolus]

I'm thinking I could write a small python script in the "utils" dir (or some python -c oneliners) to copy the generated manpages over into the data directory. This would make it platform independent, and work well on Windows.

And then we could generate the manpages and run this script through tox. That should work both locally and in CI.

[harkabeeparolus]

Done. To build a wheel with manpages included, on macOS / Linux you can do make build; on Windows, just run:

tox run -e manpages
python -m build

Remaining issues:

• I'm not thrilled about calling the directory "data". But what should it be called? "flit_external_build_data"? And where should it be placed?
  • Please bear in mind that the directory must exist at all times, or else the build will fail. So placing it inside "build", which is sometimes deleted, will not do.
• To get this across the finish line, it should also go into the GitHub workflows. I'm not 100% sure how to do that.

[picnixz]

I'm not thrilled about calling the directory "data". But what should it be called? "flit_external_build_data"

Flit has the example of having something (data)/share/man/man1/foo.1. Note that on Android, you usually have /data/data/ folder so I'd say it's fine to call it data. Alternatively, why not localdata (to stress that there is something local)?

Please bear in mind that the directory must exist at all times, or else the build will

You can always add some mkdir -p thedir in the Makefile rule if needed?