From 2dc51f1c73dede3d8f54a8fd6dbbbfb3690778d7 Mon Sep 17 00:00:00 2001
From: Bill Mills <bill.mills@linaro.org>
Date: Wed, 11 Oct 2023 15:43:17 -0400
Subject: [PATCH] Docs: enable readthedocs rendering (for PRs)

The Readthedocs pull-request integration is nice to have for PR review.
So run the whole OpenAMP-docs build but use the PR's commit

This also requires a ReadTheDocs project to install its integration for
this repo. The project should enable "Build pull request for this project".
It is currently in the Advanced Settings panel.

The project will also run for the main branch but that should be
ignored and only the main project URL should be shown outside of PRs.

To this end the sub-module project names will use "-prs" in the name.

Signed-off-by: Bill Mills <bill.mills@linaro.org>
---
 .readthedocs.yaml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 .readthedocs.yaml

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..101e29c
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,36 @@
+version: 2
+formats: all
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+  apt_packages:
+    - cmake
+    - libhugetlbfs-dev
+    - libsysfs-dev
+  # here it would be nice to tell them that the conf.py will be in openamp-docs/conf.py
+  # sphinx:
+  #   configuration: openamp-docs/conf.py
+  # HOWEVER, if we say this they check right after they do checkout and it does not exist yet
+  # As of now they find it well enough right before the build stage
+  jobs:
+    post_checkout:
+      # we ignore the checkout they did and make a new one of the whole openamp-docs project
+      - env
+      - git log -n 1 --oneline
+      - git rev-parse HEAD
+      - git clone --recurse-submodules https://github.com/OpenAMP/openamp-docs.git
+      # now adjust the focused submodule to the PR in progress
+      - echo "URL=${READTHEDOCS_GIT_CLONE_URL} COMMIT=${READTHEDOCS_GIT_COMMIT_HASH}"
+      - (cd openamp-docs/open-amp; git remote add this_pr ../../.git )
+      - (cd openamp-docs/open-amp; git fetch this_pr $(cd ../..; git rev-parse HEAD) )
+      - (cd openamp-docs/open-amp; git checkout $(cd ../..; git rev-parse HEAD) )
+      - (cd openamp-docs/open-amp; git log -n 1 --oneline)
+      - (cd openamp-docs; git submodule status)
+    post_install:
+      - python -m pip install --exists-action=w --no-cache-dir -r openamp-docs/requirements.txt
+    pre_build:
+      - echo "READTHEDOCS_OUTPUT=$READTHEDOCS_OUTPUT"
+      - make -C openamp-docs BUILDDIR=$READTHEDOCS_OUTPUT doxygen
+    post_build:
+      - make -C openamp-docs BUILDDIR=$READTHEDOCS_OUTPUT doxygen_copy