sphinx-build command not found in gitlab ci pipeline / python 3 alpine image

Question

I want to specify a GitLab job that creates a sphinx html documentation.

I am using a Python 3 alpine image (cannot specify which exactly).

the build stage within my .gitlab-ci.yml looks like this:

pages:
  stage: build
  tags: 
  - buildtag
  script:
  - pip install -U sphinx
  - sphinx-build -b html docs/ public/
  only:
  - master

however, the pipeline fails: sphinx-build: command not found. (same error for make html)

According to This Tutorial, my .gitlab-ci.yml should be more or less correct.

What am I doing wrong? Is this issue related to the alpine image I am using?

Answer 1

As @Yasen correctly noted, the path to sphinx-build was not contained in $PATH. However, adding command in before sphinx-build did not solve the problem for me.

Anyway I found the solution in the the runner logs: The output of pip install -U sphinx produced the following warning:

WARNING: The scripts sphinx-apidoc, sphinx-autogen, sphinx-build and sphinx-quickstart are installed in 'some/path' which is not on PATH.

so I added export PATH="some/path" to the script-step in the .gitlab-ci.yml:

script:
  - pip install -U sphinx
  - export PATH="some/path"
  - sphinx-build -b html docs/ public/

Answer 2

Most likely the reason is that $PATH doesn't contain path to sphinx-build

TL;DR try to use command

Try this:

pages:
  stage: build
  tags: 
  - buildtag
  script:
  - pip install -U sphinx
  - command sphinx-build -b html docs/ public/
  only:
  - master

Explanation

GitLab runners run different way

Since GitLab CI uses runners, runner's shell profile may differ from commonly used.

So, your runner may be configured without declared $PATH to the directory that contains sphinx-build

Zsh/Bash startup files loading order (.bashrc, .zshrc etc.)

See this explanation:

The issue is that Bash sources from a different file based on what kind of shell it thinks it is in. For an “interactive non-login shell”, it reads .bashrc, but for an “interactive login shell” it reads from the first of .bash_profile, .bash_login and .profile (only). There is no sane reason why this should be so; it’s just historical.

What command does mean?

Since we don't know the path where sphinx-build installed, you may use commands like: which, type, etc.

As per this great answer(shell - Why not use "which"? What to use then? - Unix & Linux Stack Exchange, author recommends to use command <name>, or $(command -v <name>)

Answer 3

Did the command pip install -U sphinx succeed? (You should be able to tell that from the CI job log.)

If so, you may need to specify the full path to sphinx-build, as Yasen said.

If it did not succeed, you should troubleshoot the installation of Sphinx.