Building manpages on sdist

Development
1

I noticed we build manpages on source distributions,

def build_manpages():
    # Go into the docs directory and build the manpage.
    docdir = os.path.join(os.path.dirname(__file__), 'docs')
    curdir = os.getcwd()
    os.chdir(docdir)
    try:
        subprocess.check_call(['make', 'man'])
    except OSError:
        print("Could not build manpages (make man failed)!", file=sys.stderr)
        return
    finally:
        os.chdir(curdir)

    # Copy resulting manpages.
    mandir = os.path.join(os.path.dirname(__file__), 'man')
    if os.path.exists(mandir):
        shutil.rmtree(mandir)
    shutil.copytree(os.path.join(docdir, '_build', 'man'), mandir)


# Build manpages if we're making a source distribution tarball.
if 'sdist' in sys.argv:
    build_manpages()

and I thought it seemed odd, so I googled around to see if this was the norm, and I found some arguments against it.

Also, I believe this is the reason sphinx needs to be installed prior to building with tox. Which makes sphinx a build-time dependency, which is not really what we want.

$ tox -e docs
GLOB sdist-make: /home/jacob/src/beets/setup.py
ERROR: invocation failed (exit code 1), logfile: /home/jacob/src/beets/.tox/log/GLOB-0.log
===================================================================================================================================== log start ======================================================================================================================================
sphinx-build -b man -d _build/doctrees   . _build/man
make: sphinx-build: Command not found
make: *** [Makefile:117: man] Error 127
Traceback (most recent call last):
  File "setup.py", line 54, in <module>
    build_manpages()
  File "setup.py", line 38, in build_manpages
    subprocess.check_call(['make', 'man'])
  File "/usr/lib/python3.8/subprocess.py", line 364, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['make', 'man']' returned non-zero exit status 2.

====================================================================================================================================== log end =======================================================================================================================================
ERROR: FAIL could not package project - v = InvocationError('/usr/bin/python setup.py sdist --formats=zip --dist-dir .tox/dist', 1)

Basically, my question is, what is the reason that we do this, and should we continue to do it/are there better options?

Pinging @jackwilsdon and @adrian since I know they’ve both worked on this before.

2

Yep, you’ve got it right. That’s why Sphinx is a build-time dependency.

Basically, we added this so that you could get a manpage when you type pip install beets, which is the way that most people install beets (AFAIK). Those other criticisms from the page you linked notwithstanding, that seems like a pretty solid usability win.

The only other way I can think of to do this is perhaps to start distributing wheels?? This would need some experimentation, however, to see how possible it is to include the manpage in the wheel, and whether it successfully installs after doing that. Maybe something like Flit could help.

3

How can I access the manpages with a normal pip install beets?

Edit: to disprove the obvious, man beet or similar doesn’t work for me.

4

Wow, thanks for making me take another look! I think I was completely wrong. Somehow I got it in my head that we did this so pip install could install manpages, but apparently we never did that? We would need to have used data_files in setup.py, and apparently we are not currently doing that. How about that!

The argument against is now quite a bit stronger. Of course, the disruption will now be on the end of all the packagers—the people who maintain packages for Debian, Arch, etc. If we make a change to how we distribute this, they will need to take up the slack and add Sphinx to their build-time dependencies. So we would probably want to warn them ahead of time.

5

I think this makes the most sense.

This also means anyone developing beets (+ our github actions) won’t get surprised running tox only to find out sphinx is needed before you can build.

1 Like