Running nbsphinx on GitLab

[kolibril13]

Similar to ReadTheDocs, GitLab Pages can also run sphinx content. While readthedocs comes with pandoc by default, Gitlab pages does not.

Here is a .gitlab-ci.yml script that is not working:

image: python

pages:
  stage: deploy
  script:
    - pip install numpy ipykernel
    - pip install sphinx furo nbsphinx sphinx-copybutton
    - mkdir -p doc; cd doc
    - sphinx-build -b html source ../public/
    - echo 'Done'
  artifacts:
    paths:
      - public
  only:
    - master

Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
Cleaning up file based variables
00:01
ERROR: Job failed: exit code 1

Instead, I found this image : https://hub.docker.com/r/ashwinvis/latex-pandoc-python that is working:

image: ashwinvis/latex-pandoc-python

pages:
  stage: deploy
  script:
    - pip install numpy ipykernel
    - pip install sphinx furo nbsphinx 
    - mkdir -p doc; cd doc
    - sphinx-build -b html source ../public/
    - echo 'Done'
  artifacts:
    paths:
      - public
  only:
    - master

-> Build successful.

That took quite some time to figure out, and it would be great if others don't go through the same struggle. Therefore the question: should this be added to the docs? In case that yes, there is a drawback: This docker image is already 2 years old, so it runs Python 3.6. Further, an idea: there could be a newer docker image, that already includes a modern python, ipykernel, sphinx and nbsphinx. I am not an expert in docker, but in case that someone here is: What do you think about making a nbsphinx docker image?

[mgeier]

should this be added to the docs?

Yes, sure, why not!

What do you think about making a nbsphinx docker image?

I don't really want to maintain such an image, and I think a special Docker image just for nbsphinx would be overkill.

I don't know about GitLab, but on many CI services one can install packages with apt-get, which has a pandoc package. A simple sudo apt-get install pandoc might be enough.

If apt-get (or a similar package manager) is not available, probably conda can be used? The conda-forge channel has a pandoc package (see https://nbsphinx.readthedocs.io/en/0.8.6/installation.html#pandoc).

And if you want to try a more recently updated Dockerfile, you can have a look at https://hub.docker.com/u/pandoc.

[mgeier]

This has been addressed in #597.