From 69eda9d882532d4ac46d755a891607628ee4946b Mon Sep 17 00:00:00 2001 From: Samuel Dowling Date: Sun, 5 Dec 2021 11:44:32 +1030 Subject: [PATCH] 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 #81 --- docs/gitlab_pages.rst | 90 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 91 insertions(+) create mode 100644 docs/gitlab_pages.rst diff --git a/docs/gitlab_pages.rst b/docs/gitlab_pages.rst new file mode 100644 index 00000000..58310f35 --- /dev/null +++ b/docs/gitlab_pages.rst @@ -0,0 +1,90 @@ +.. _gitlab_pages: + +======================= +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``. + +.. 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 + + + + Redirecting to $CI_DEFAULT_BRANCH branch + + + + + + 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 index 0b2b543a..01284685 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,5 +24,6 @@ Project Links :caption: Appendix github_pages + gitlab_pages faq changelog