Merge pull request #1453 from alan-turing-institute/readthedocs

Migrate docs to readthedocs.io

.github/workflows/documentation.yaml

@@ -0,0 +1,56 @@
+---
+name: Documentation
+
+# Run workflow on pushes to matching branches
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs/
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+      - name: Sphinx build
+        run: |
+          make html
+
+  check_links:
+    name: Check links
+    runs-on: ubuntu-latest
+    needs: build
+    defaults:
+      run:
+        working-directory: ./docs/
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+      - name: Sphinx build
+        run: |
+          make html
+      - name: Link Checker
+        uses: lycheeverse/[email protected]
+        with:
+          args: --config='./.lychee.toml' --verbose --no-progress './docs/build/html/**/*.html'
+          fail: true  # fail on broken links

.github/workflows/lint_code.yaml

@@ -9,32 +9,6 @@ on:  # yamllint disable-line rule:truthy
     branches: [develop]
 
 jobs:
-  lint_html:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-      - name: Get tags
-        run: git fetch --tags origin
-      - name: Install requirements
-        shell: bash
-        run: |
-          sudo gem install html-proofer -v 4.4.1
-          pip install -r docs/build/requirements.txt
-      - name: Generate HTML documention
-        shell: bash
-        run: |
-          DISABLE_VERSION_LINKS=1 make -C docs html
-      - name: Lint HTML
-        shell: bash
-        run: |
-          htmlproofer docs/_output \
-            --allow-missing-href=true \
-            --enforce-https=true \
-            --ignore-files "/_static/" \
-            --ignore-status-codes "502,503" \
-            --ignore-urls "/github.com\/alan-turing-institute\/data-classification-app/,/www.turing.ac.uk/,/data-safe-haven\/edit/"
-
   lint_json:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -33,4 +33,7 @@ docs/_output
 
 # Files produced during testing
 .mustache_config.json
-expanded.yaml
+expanded.yaml
+
+# Lychee cache
+.lycheecache

.lychee.toml

@@ -0,0 +1,123 @@
+#############################  Display  #############################
+
+# Verbose program output
+# Accepts log level: "error", "warn", "info", "debug", "trace"
+verbose = "info"
+
+# Don't show interactive progress bar while checking links.
+no_progress = false
+
+# Path to summary output file.
+# output = ".config.dummy.report.md"
+
+#############################  Cache  ###############################
+
+# Enable link caching. This can be helpful to avoid checking the same links on
+# multiple runs.
+cache = true
+
+# Discard all cached requests older than this duration.
+max_cache_age = "1d"
+
+#############################  Runtime  #############################
+
+# Number of threads to utilize.
+# Defaults to number of cores available to the system if omitted.
+threads = 2
+
+# Maximum number of allowed redirects.
+max_redirects = 10
+
+# Maximum number of allowed retries before a link is declared dead.
+max_retries = 2
+
+# Maximum number of concurrent link checks.
+max_concurrency = 14
+
+#############################  Requests  ############################
+
+# User agent to send with each request.
+user_agent = "curl/7.83. 1"
+
+# Website timeout from connect to response finished.
+timeout = 20
+
+# Minimum wait time in seconds between retries of failed requests.
+retry_wait_time = 2
+
+# Comma-separated list of accepted status codes for valid links.
+accept = [200, 429]
+
+# Proceed for server connections considered insecure (invalid TLS).
+insecure = false
+
+# Only test links with the given schemes (e.g. https).
+# Omit to check links with any scheme.
+# scheme = [ "https" ]
+
+# When links are available using HTTPS, treat HTTP links as errors.
+require_https = true
+
+# Request method
+method = "get"
+
+# Custom request headers
+headers = []
+
+# Remap URI matching pattern to different URI.
+# remap = [ "https://example.com http://example.invalid" ]
+
+# Base URL or website root directory to check relative URLs.
+# base = "https://example.com"
+
+# HTTP basic auth support. This will be the username and password passed to the
+# authorization HTTP header. See
+# <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>
+# basic_auth = "user:pwd"
+
+#############################  Exclusions  ##########################
+
+# Skip missing input files (default is to error if they don't exist).
+skip_missing = false
+
+# Check links inside `<code>` and `<pre>` blocks as well as Markdown code
+# blocks.
+include_verbatim = false
+
+# Ignore case of paths when matching glob patterns.
+glob_ignore_case = false
+
+# Exclude URLs and mail addresses from checking (supports regex).
+# exclude = [ '.*\.github.com\.*' ]
+exclude = [
+  'github\.com',  # Requires authentication (403)
+  'turing\.ac\.uk',  # DDOS protection
+  'ipaddressguide\.com', # 403
+  'opensource\.org' # 403
+]
+
+# Exclude these filesystem paths from getting checked.
+# exclude_path = ["file/path/to/Ignore", "./other/file/path/to/Ignore"]
+exclude_path = [
+  'docs/build/html/_static/webpack-macros.html'
+]
+
+# URLs to check (supports regex). Has preference over all excludes.
+# include = [ 'gist\.github\.com.*' ]
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
+exclude_all_private = false
+
+# Exclude private IP address ranges from checking.
+exclude_private = false
+
+# Exclude link-local IP address range from checking.
+exclude_link_local = false
+
+# Exclude loopback IP address range and localhost from checking.
+exclude_loopback = false
+
+# Exclude all mail addresses from checking.
+exclude_mail = false

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+# formats:
+#    - pdf
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "To acknowledge the data safe haven please use the citation and references below."
 title: "Turing Data Safe Haven"
-url: "https://alan-turing-institute.github.io/data-safe-haven/develop/index.html"
+url: "https://data-safe-haven.readthedocs.io"
 repository-code: "https://github.com/alan-turing-institute/data-safe-haven"
 authors:
   - given-names: James

CONTRIBUTING.md

@@ -222,7 +222,7 @@ GitHub has a [nice introduction](https://docs.github.com/en/get-started/quicksta
 
 ### Making a change to the documentation
 
-The docs, including for older releases, are available [here](https://alan-turing-institute.github.io/data-safe-haven).
+The docs, including for older releases, are available [here](https://data-safe-haven.readthedocs.io).
 
 You should follow the same instructions as above to [make a change with a pull request](#making-a-change-with-a-pull-request) when editing the documentation.
 

README.md

@@ -1,12 +1,12 @@
-![Data Safe Haven cartoon by Scriberia for The Alan Turing Institute](docs/static/scriberia_diagram.jpg)
+![Data Safe Haven cartoon by Scriberia for The Alan Turing Institute](docs/_static/scriberia_diagram.jpg)
 
 # :eyes: What is the Turing Data Safe Haven?
 
 The **Turing Data Safe Haven** is an open-source framework for creating secure environments to analyse sensitive data.
 It provides a set of scripts and templates that will allow you to deploy, administer and use your own secure environment.
 It was developed as part of the Alan Turing Institute's [Data Safe Havens in the Cloud](https://www.turing.ac.uk/research/research-projects/data-safe-havens-cloud) project.
 
-[![Docs](https://github.com/alan-turing-institute/data-safe-haven/actions/workflows/build_docs.yaml/badge.svg)](https://alan-turing-institute.github.io/data-safe-haven)
+[![Documentation](https://readthedocs.org/projects/data-safe-haven/badge/?version=latest)](https://data-safe-haven.readthedocs.io/en/latest/?badge=latest)
 [![Lint code](https://github.com/alan-turing-institute/data-safe-haven/actions/workflows/lint_code.yaml/badge.svg)](https://github.com/alan-turing-institute/data-safe-haven/actions/workflows/lint_code.yaml)
 [![Test code](https://github.com/alan-turing-institute/data-safe-haven/actions/workflows/test_code.yaml/badge.svg)](https://github.com/alan-turing-institute/data-safe-haven/actions/workflows/test_code.yaml)
 [![Latest version](https://img.shields.io/github/v/release/alan-turing-institute/data-safe-haven?style=flat&label=Latest&color=%234B78E6)](https://github.com/alan-turing-institute/data-safe-haven/releases)
@@ -16,7 +16,7 @@ It was developed as part of the Alan Turing Institute's [Data Safe Havens in the
 
 ## :family: Community & support
 
-- Visit the [Data Safe Haven website](https://alan-turing-institute.github.io/data-safe-haven) for full documentation and useful links.
+- Visit the [Data Safe Haven website](https://data-safe-haven.readthedocs.io) for full documentation and useful links.
 - Join our [Slack server](https://join.slack.com/t/turingdatasafehaven/shared_invite/zt-104oyd8wn-DyOufeaAQFiJDlG5dDGk~w) to ask questions, discuss features, and for general API chat.
 - Open a [discussion on GitHub](https://github.com/alan-turing-institute/data-safe-haven/discussions) for general questions, feature suggestions, and help with our deployment scripts.
 - Look through our [issues on GitHub](https://github.com/alan-turing-institute/data-safe-haven/issues) to see what we're working on and progress towards specific fixes.