DEV: added scripts for building and uploading docs (#111)

* Update .readthedocs.yaml

* Update .readthedocs.yaml

* Update .readthedocs.yaml

* Update .readthedocs.yaml

* Update .readthedocs.yaml

* Update .readthedocs.yaml

* DEV: added GHA for building docs

* Update build_docs.yml

* Update build_docs.yml

* Update build_docs.yml

* Update build_docs.yml

* Update build_docs.yml

* Update build_docs.yml

* Update build_docs.yml

* Update build_docs.yml

* DEV: update doc yaml's

* DEV: more tweaks

* added python script for downloading docs

* debug

* debug

* fix url error

* MAINT: added a comment about usage of the python script

* STY: fix linting issues with doc script

* DEV: use cached iqtree build when making docs

* DEV: use iqtree/piqtree2 for api url

---------

Co-authored-by: Robert McArthur <robert.mcarthur@anu.edu.au>

Author: GavinHuttley

.github/workflows/build_docs.yml

@@ -0,0 +1,68 @@
+name: Build docs
+
+on: [workflow_dispatch]
+
+jobs:
+  build-iqtree:
+    name: Fetch or Build IQ-TREE 2 Static Library
+    runs-on: ubuntu-latest
+    steps:
+      - uses: "actions/checkout@v4"
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Get IQ-TREE 2 SHA
+        run: |
+          cd iqtree2
+          IQ_TREE_2_SHA=$(git rev-parse HEAD)
+          echo "IQ_TREE_2_SHA=${IQ_TREE_2_SHA}" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          key: libiqtree-${{ matrix.os }}-${{ env.IQ_TREE_2_SHA }}
+          path: src/piqtree2/_libiqtree/libiqtree2.a
+          lookup-only: true
+      
+      - name: Build IQ-TREE
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          sudo ./build_tools/before_all_linux.sh
+          
+  build-docs:
+    runs-on: ubuntu-latest
+    needs: build-iqtree
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - uses: actions/cache/restore@v4
+        with:
+          key: libiqtree-ubuntu-latest-${{ env.IQ_TREE_2_SHA }}
+          path: src/piqtree2/_libiqtree/libiqtree2.a
+          fail-on-cache-miss: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      
+      - name: Install Docs Dependencies
+        run: |
+          pip install .[doc]
+
+      - name: Build documentation
+        run: |
+          echo `pwd`
+          mkdocs build
+        working-directory: ${{ github.workspace }}
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: piqtree-docs-html
+          path: site

.readthedocs.yaml

@@ -10,17 +10,16 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
-jobs:
-    post_checkout:
-      - git submodule update --init --recursive
+  commands:
+    # Install the required dependencies
+    - pip install requests
+    # Run the script to download and extract the pre-built docs
+    - python rtd_get_docs.py
+    - echo "Documentation downloaded and extracted"
 
-mkdocs:
-  configuration: mkdocs.yml
+# Disable the default build processes since we're using pre-built docs
+sphinx:
+  configuration: null
 
-# Optionally declare the Python requirements required to build your docs
 python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - doc
+  install: []

rtd_get_docs.py

@@ -0,0 +1,39 @@
+# this file
+# is directly used by .readthedocs.yaml
+# it extracts the built docs from the github artefact
+# created by the build_docs.yml github action
+import os
+import pathlib
+import zipfile
+
+import requests
+
+
+def download_and_extract_docs() -> None:
+    token = os.environ.get("GITHUB_TOKEN")
+    headers = {"Authorization": f"token {token}"}
+    api_url = "https://api.github.com/repos/iqtree/piqtree2/actions/runs"
+    response = requests.get(api_url, headers=headers, timeout=10)
+    got = response.json()
+    runs = got["workflow_runs"]
+    latest_run = next(
+        run
+        for run in runs
+        if run["name"] == "Build docs" and run["conclusion"] == "success"
+    )
+    artifacts_url = latest_run["artifacts_url"]
+    response = requests.get(artifacts_url, headers=headers, timeout=10)
+    artifacts = response.json()["artifacts"]
+    docs_artifact = next(
+        artifact for artifact in artifacts if artifact["name"] == "piqtree-docs-html"
+    )
+    download_url = docs_artifact["archive_download_url"]
+    response = requests.get(download_url, headers=headers, timeout=10)
+    out = pathlib.Path("piqtree-docs-html.zip")
+    out.write_bytes(response.content)
+    with zipfile.ZipFile("piqtree-docs-html.zip", "r") as zip_ref:
+        zip_ref.extractall("_readthedocs/html/")
+
+
+if __name__ == "__main__":
+    download_and_extract_docs()