made improvements

doc/usage.ipynb

@@ -700,26 +700,41 @@
     "\n",
     "When using GitLab pages, you can use nbsphinx by adding the file `.gitlab-ci.yml` to your repo and copying the following lines into this file:\n",
     "```\n",
-    "image: python\n",
-    "\n",
-    "before_script:\n",
-    "  - apt-get update -y\n",
-    "  - apt-get install -y pandoc\n",
+    "image: python:3-slim\n",
     "\n",
+    "variables:\n",
+    "  PIP: python3 -m pip\n",
+    "  SPHINX: python3 -m sphinx -W --keep-going --color\n",
     "\n",
+    "build-docs:\n",
+    "  stage: build\n",
+    "  script:\n",
+    "    - apt-get update -y\n",
+    "    - apt-get install -y --no-install-recommends pandoc\n",
+    "    - $PIP install -r doc/requirements.txt\n",
+    "    - $SPHINX -d doctrees doc html -b html\n",
+    "    - $SPHINX -d doctrees doc linkcheck -b linkcheck\n",
+    "  artifacts:\n",
+    "    when: always\n",
+    "    paths:\n",
+    "      - html\n",
+    "      - linkcheck/output.*\n",
+    "    \n",
     "pages:\n",
     "  stage: deploy\n",
+    "  variables:\n",
+    "    GIT_STRATEGY: none\n",
     "  script:\n",
-    "    - pip install numpy ipykernel\n",
-    "    - pip install sphinx nbsphinx\n",
-    "    - mkdir -p doc; cd doc\n",
-    "    - sphinx-build -b html source ../public/\n",
+    "    - mv html public\n",
     "  artifacts:\n",
     "    paths:\n",
     "      - public\n",
-    "  only:\n",
-    "    - master\n",
-    "```"
+    "  rules:\n",
+    "    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH\n",
+    "```\n",
+    "Note:  \n",
+    "\n",
+    "You migh have to change the line `docs/` to `docs/source` in case that you have this folder structure, which is the default when using `sphinx-quickstart. "
    ]
   },
   {
@@ -925,4 +940,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}