Hosting on GitLab Pages¶

You use GitLab Pages to host documentation generated by sphinx-multiversion.

Configure your project¶

Because of the way GitLab checks out a repository when running a CI task, you’ll need to whitelist remote branches in your conf.py.

smv_remote_whitelist = r'^(origin)$'

If this is not specified, sphinx-multiversion will only be able to generate documentation for whitelisted tag patterns.

Create `.gitlab-ci.yml`¶

GitLab pages always deploys your website from a specific folder called public in your repository. To deploy to your site, GitLab pages uses its built in continuous integration tools to build your site and publish it to the GitLab server. To accomplish this, you need to create a .gitlab-ci.yml in your repository. This recipe will build your documentation, move it to a folder named public, and then create an artifact compressing this folder. Populate it as follows.

test:
  image: python:latest
  stage: test
  before_script:
    - export
    - apt update -y
    - apt install -y texlive latexmk texlive-latex-extra # only necessary for pdf generation
    - pip install -r requirements.txt
  script:
    - sphinx-multiversion docs/source/ public
  tags:
    - docker # may need removal depending on what available GitLab runners are tagged with
    - bash
  only:
    - branches
  except:
    - master

pages:
  image: python:latest
  stage: deploy
  before_script:
    - export
    - apt update -y
    - apt install -y texlive latexmk texlive-latex-extra # only necessary for pdf generation
    - pip install -r requirements.txt
  script:
    - sphinx-multiversion docs/source public
    - | # Add index.html to public root to redirect to $CI_DEFUALT_BRANCH/index.html
      cat >public/index.html << EOF
      <!DOCTYPE html>
        <html>
          <head>
            <title>Redirecting to $CI_DEFAULT_BRANCH branch</title>
            <meta charset="utf-8">
            <meta http-equiv="refresh" content="0; url=./$CI_DEFAULT_BRANCH/index.html">
            <link rel="canonical" href="$CI_PAGES_URL/$CI_DEFAULT_BRANCH/index.html">
          </head>
        </html>
      EOF
  tags:
    - docker # may need removal depending on what available GitLab runners are tagged with
    - bash
  artifacts:
    paths:
      - public
  only:
    - develop

This will create two jobs. The first job will test that documentation generation will complete successfully. This will run for every branch with the exception of master. The second task will deploy the generated documents to the GitLab pages server. This task will run only on changes to the develop branch. These rules should be updated to reflect your desired behaviour. Note that this includes the addition of a dummy index.html to the root of your GitLab public directory that redirects to documentation on the $CI_DEFAULT_BRANCH.

Hosting on GitLab Pages¶

Configure your project¶

Create .gitlab-ci.yml¶

Create `.gitlab-ci.yml`¶