Added Installation guide for Gitlab Pages

[kolibril13]

Again, same as #590

[mgeier]

Thanks for the update!

I've left a few comments and questions.

[mgeier]

I normally like to add the --no-install-recommends, which might speed up the installation.

I've also just added this to nbsphinx's own CI: #598.

[kolibril13]

Sounds good!
But when the new nbspinx version will have it on default, will " - apt-get install -y pandoc\n", be needed at all?

[mgeier]

I don't understand. It will still need pandoc (at least until #36 is done).

[mgeier]

What about recommending the usage of a doc/requirements.txt instead?

[kolibril13]

I'd prefer it like this, then it is ready for copy+paste

[mgeier]

OK, fair enough.

[mgeier]

Sphinx is a dependency of nbsphinx, so it's not strictly necessary.

But if you prefer to mention it, that's fine.

[mgeier]

What is that supposed to mean?

Is there no doc directory yet?
Where is the source directory?

[kolibril13]

I saw this somewhere on the internet and as it was working, I just applied it without spending much thought on it.

[mgeier]

But I don't understand how this can work.

According to the sphinx-build call below, your source files are in doc/source but why are you creating the doc directory? It should exist already?

[mgeier]

I think this will create a ../public/.doctrees directory which is not supposed to be published.

I think it would be good to use the -d to put the doctrees somewhere else.

Or are hidden directories ignored by Gitlab Pages anyway?

[kolibril13]

Again, this is only copy-pasted form some internet forums, I don't know about the details

[mgeier]

That's fine, but do you know if the .doctree directory is served by Gitlab pages?
Do you have an example project where I can have a look?

[kolibril13]

Thanks for your review!
I am a bit busy right now, but I'll have a look on it soon.

[kolibril13]

Thanks @mgeier for your in-depth review!
To be honest, I really don't know much about gitlab workflows, and this script is something that performed good for me and I wanted to share it to others, who also might want to use nbsphinx in gitlab. I don't have so much clue about optimizing these lines, and also, I currently don't have much time/not the priority to figure that out, so please feel free to push any changes that you think are appropriate on this branch, and thanks again for your review! :)

[mgeier]

I did some experiments with Docker and Gitlab and came up with this example .gitlab-ci.yml:

image: python:3-slim

variables:
  PIP: python3 -m pip
  SPHINX: python3 -m sphinx -W --keep-going --color

build-docs:
  stage: build
  script:
    - apt-get update -y
    - apt-get install -y --no-install-recommends pandoc
    - $PIP install -r doc/requirements.txt
    - $SPHINX -d doctrees doc html -b html
    - $SPHINX -d doctrees doc linkcheck -b linkcheck
  artifacts:
    when: always
    paths:
      - html
      - linkcheck/output.*
    
pages:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script:
    - mv html public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

For this to work, the file conf.py and the source files must be in the doc/ directory. And there must be a doc/requirements.txt containing all requirements, including nbsphinx (and ipykernel if notebooks are supposed to be executed with IPython).

IMHO, this has a few advantages:

• it builds the docs on all branches and MRs and provides the HTML files to browse (but it still only deploys to Gitlab Pages on the main branch)
• it uses requirements.txt, which can also be used by people who check out the repo locally, no need to duplicate the dependencies
• it also runs the linkcheck builder, which I think is great and many people don't know about it (but it's easy to disable if somebody doesn't like it)
• it uses -Wto turn warnings into errors (but it doesn't stop immediately due to --keep-going)
  • this should probably be explained in the text
• it uses a smaller Docker image
• it uses more modern config parameters (e.g. rules)

What do you think about that?

[kolibril13]

Hi @mgeier ,
sorry for my very delayed reply.
Unfortunately, I am really involved in other open-source projects right now, so I don't have the capacity to work on this pr.
Nevertheless, I tested your script on a repo that I created extra for this reason:
https://gitlab.gwdg.de/jan-hendrik.mller/okapi42
and I did not get it to work.
First of all, it did give me the error:
config directory doesn't contain a conf.py file (/builds/jan-hendrik.mller/okapi42/doc)
see log here: https://gitlab.gwdg.de/jan-hendrik.mller/okapi42/-/jobs/701975
When the conf.py was at okapi42/doc/source.
Still changing the whole folder structure gave me then this error.
https://gitlab.gwdg.de/jan-hendrik.mller/okapi42/-/jobs/701983
I hope this will help you to build a nice GitLab pipeline with nbsphinx.

[mgeier]

Thanks for trying this out @kolibril13!

As you have seen, the source directory is unnecessary, but if you like to use it nevertheless, you can just change the Sphinx call to use doc/source instead of doc.
However, I think it is much less confusing for newcomers to just get rid of the source subdirectory.

Your second error is just a warning-turned-into-an-error. If you don't want this to happen, you can remove the -W flag from the Sphinx call. However, I highly recommend to keep it and to fix the warning instead.
In this case, the warning is:

WARNING: html_static_path entry '_static' does not exist

There are two ways to fix this: either you remove the unused setting html_static_path = ['_static'] from your conf.py, or you create the _static directory that is referenced in this setting.

[kolibril13]

or you create the _static directory

Nice, that fixed it! :)

Thanks for taking time and writing the GitLab script, I've just updated this pr with your script.

[mgeier]

Sorry for the long delay, I've merged your PR now.

[kolibril13]

Not problem!
Thanks! :)

[mgeier]

I forgot to squash your commits, I've done that now in 8f6343a.