Unmet dependencies to use accessibility check leads to poor UX

[pmatulis]

The accessibility check is applied via the pa11y make target:

pa11y: pa11y-install html
    find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)

This calls the pa11y-install make target:

pa11y-install:
    @type $(PA11Y) >/dev/null 2>&1 || { \
            echo "Installing \"pa11y\" from npm... \n"; \
            mkdir -p $(SPHINXDIR)/node_modules/ ; \
            npm install --prefix $(SPHINXDIR) pa11y; \
        }

This assumes the npm package manager is available on the host system and will report an error if it is not:

make pa11y
Installing "pa11y" from npm...

/bin/sh: 4: npm: not found
make: *** [Makefile:56: pa11y-install] Error 127

The software should first conduct a check for the presence of npm and, if not found, bail with a user-friendly message. The user needs to do:

sudo apt install npm

[akcano]

@pmatulis I see your point and thought about that, too. However, I have two concerns about such a move:

• Currently, we make the same assumptions about other package managers (e.g. snap). While npm may not be as ubiquitous, it's roughly in the same semantic category: we provide commands to install specific tools, but assume their respective origins (snap, npm) are available.

• Almost notoriously, npm can be installed in a variety of ways, and we shouldn't force a specific choice on the user if there's a chance of their having a preference here.

[pmatulis]

Perhaps this is a documentation fail then. We should specify requirements in the README.

[akcano]

Good point, I'll add a note.

[akcano]

@pmatulis https://github.com/canonical/sphinx-docs-starter-pack/pull/189