81: Add GitLab Pages deployment instructions

* Add GitLab pages deployment instructions to make it easier for those using GitLab pages to understand how sphinx-multiversion might be integrated. * Update index.rst to include GitLab pages in the navigation menu to facilitate discoverability Closes sphinx-contrib#81
samuel-emrys · Dec 5, 2021 · 69eda9d · 69eda9d
1 parent cdc9cb5
commit 69eda9d
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 0 deletions.
diff --git a/docs/gitlab_pages.rst b/docs/gitlab_pages.rst
@@ -0,0 +1,90 @@
+.. _gitlab_pages:
+
+=======================
+Hosting on GitLab Pages
+=======================
+
+You use `GitLab Pages <gitlab_pages_website>`_ 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``.
+
+.. code-block:: python
+
+   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.
+
+.. code-block:: yaml
+
+   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 :file:`index.html` to the root of your GitLab ``public`` directory that redirects to documentation on the ``$CI_DEFAULT_BRANCH``.
+
+.. seealso::
+
+   A list of predefined environment variables available for use in ``.gitlab-ci.yml`` is available in the `GitLab Predefined variables reference <_gitlab_predefined_variables>`_.
+
+For deployments to ``.gitlab.com``, the default domain for GitLab pages websites is ``*.gitlab.io``. Your documentation should be available at ``https://username.gitlab.io/reponame``.
+
+.. seealso::
+
+    For details, please have a look at the `GitLab Pages Documentation <_gitlab_pages_tutorial>`_.
+
+.. _gitlab_pages_website: https://docs.gitlab.com/ee/user/project/pages/
+.. _gitlab_pages_tutorial: https://docs.gitlab.com/ee/user/project/pages/getting_started/pages_from_scratch.html
+.. _gitlab_predefined_variables: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
diff --git a/docs/index.rst b/docs/index.rst
@@ -24,5 +24,6 @@ Project Links
     :caption: Appendix
 
     github_pages
+    gitlab_pages
     faq
     changelog