From 3abfdbab724bd0f54055b14f6529f4ed255b9f26 Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Tue, 24 Jul 2018 16:57:40 -0700
Subject: [PATCH] doc: add script for syncing acrn-kernel for API gen

API doc generation includes kernel components provided by ACRN that live
in the acrn-kernel repo (not the acrn-hypervisor repo). We need to
include fetching the latest acrn-kernel sources when we do doc
generation, and update the documentation to mention we now need the
acrn-kernel repo as a sibling folder for the acrn-hypervisor repo
contents.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
---
 doc/Makefile               |  4 ++++
 doc/scripts/pullsource.sh  | 17 +++++++++++++++++
 doc/tutorials/docbuild.rst | 20 +++++++++++++++++++-
 3 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100755 doc/scripts/pullsource.sh

diff --git a/doc/Makefile b/doc/Makefile
index 47b073868..a74149dac 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -48,6 +48,10 @@ kconfig:
 	$(Q)srctree=../hypervisor \
 	    python3 scripts/genrest.py ../hypervisor/Kconfig reference/kconfig/
 
+pullsource:
+	$(Q)scripts/pullsource.sh
+
+
 html: doxy content kconfig
 	-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> doc.log 2>&1
 	$(Q)./scripts/filter-doc-log.sh doc.log
diff --git a/doc/scripts/pullsource.sh b/doc/scripts/pullsource.sh
new file mode 100755
index 000000000..0fa9ca3d3
--- /dev/null
+++ b/doc/scripts/pullsource.sh
@@ -0,0 +1,17 @@
+#!/bin/bash
+
+q="--quiet"
+
+# get the latest acrn-kernel sources for the kernel-doc API processing
+
+if [ ! -d "../../acrn-kernel" ]; then
+  echo Repo for acrn-kernel is missing.
+  exit -1
+fi
+
+# Assumes origin is the upstream repo
+
+cd ../../acrn-kernel
+git checkout $q master
+git fetch $q origin
+git reset $q --hard origin/master
diff --git a/doc/tutorials/docbuild.rst b/doc/tutorials/docbuild.rst
index 63575ad93..5536252c5 100644
--- a/doc/tutorials/docbuild.rst
+++ b/doc/tutorials/docbuild.rst
@@ -66,9 +66,14 @@ generation:
          devicemodel/
          doc/
          hypervisor/
+      acrn-kernel
 
 The parent projectacrn folder is there because we'll also be creating a
-publishing area later in these steps.  It's best if the acrn-hypervisor
+publishing area later in these steps.  For API doc generation, we'll also
+need the acrn-kernel repo contents in a sibling folder to the
+acrn-hypervisor repo contents. 
+
+It's best if the acrn-hypervisor
 folder is an ssh clone of your personal fork of the upstream project
 repos (though https clones work too):
 
@@ -96,6 +101,19 @@ repos (though https clones work too):
       cd acrn-hypervisor
       git remote add upstream git@github.com:projectacrn/acrn-hypervisor.git
 
+#. For API doc generation we'll also need the acrn-kernel repo available
+   locally:
+
+   .. code-block:: bash
+
+      cd ..
+      git clone git@github.com:projectacrn/acrn-kernel.git
+
+   .. note:: We assume for doc generation that ``origin`` is pointed to
+      the upstream repo.  If you're a developer and have the acrn-kernel
+      repo allready set up as a sibling folder to the acrn-hypervisor,
+      you can skip this clone step.
+
 #. If you haven't do so already, be sure to configure git with your name
    and email address for the signed-off-by line in your commit messages: