Docs: enable readthedocs rendering (for PRs)

.readthedocs.yaml

@@ -0,0 +1,35 @@
+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/libmetal; git remote add this_pr ${READTHEDOCS_GIT_CLONE_URL}; git fetch this_pr )
+      - (cd openamp-docs/libmetal; git checkout $(cd ../..; git rev-parse HEAD) )
+      - (cd openamp-docs/libmetal; 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

doc/CMakeLists.txt

@@ -1,11 +1,23 @@
 if (DOXYGEN_FOUND)
 
-  configure_file (Doxyfile.in Doxyfile @ONLY)
+  if (EXISTS ${CMAKE_SOURCE_DIR}/../_doxygen/openamp/Doxyfile-openamp.in)
+    set (OAMP_DOX_DIR ${CMAKE_SOURCE_DIR}/../_doxygen/openamp)
+    configure_file (Doxyfile.in Doxyfile1 @ONLY)
+    configure_file (${OAMP_DOX_DIR}/Doxyfile-openamp.in Doxyfile2 @ONLY)
 
-  add_custom_target (doc ALL
-    ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-  )
+    add_custom_target (doc ALL
+      COMMAND cat Doxyfile1 Doxyfile2 >Doxyfile
+      COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    )
+  else ()
+    configure_file (Doxyfile.in Doxyfile @ONLY)
+
+    add_custom_target (doc ALL
+      ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    )
+  endif ()
 
 install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
   DESTINATION share/doc/${PROJECT_NAME})