From 38f8097b545be46e9a58bc1123dad839b5c66bd3 Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Wed, 19 Oct 2022 09:27:45 -0700
Subject: [PATCH] doc: update doc build tools for Ubuntu 22.04 and Sphinx

Update known-issues processing and tweak conf.py and requirements.txt
(for PyPI package versions) to handle a broader version of
doc-generation tools (sphinx, breathe, docutils, etc.).  This should
let us move to Ubuntu 22.04 while maintaining doc-build compatibility
with older tool versions available with Ubuntu 20.04 (doxygen in particular).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
---
 doc/.known-issues/doc/sphinx.conf |  5 +++++
 doc/conf.py                       |  6 +++---
 doc/scripts/requirements.txt      | 10 +++++-----
 3 files changed, 13 insertions(+), 8 deletions(-)
 create mode 100644 doc/.known-issues/doc/sphinx.conf

diff --git a/doc/.known-issues/doc/sphinx.conf b/doc/.known-issues/doc/sphinx.conf
new file mode 100644
index 000000000..3813580a1
--- /dev/null
+++ b/doc/.known-issues/doc/sphinx.conf
@@ -0,0 +1,5 @@
+# Known Sphinx generation messages to ignore
+#
+#
+^WARNING: extlinks: Sphinx-6.0 will require a caption string to contain exactly.*$
+#
diff --git a/doc/conf.py b/doc/conf.py
index f086ee381..31eb175fd 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -45,8 +45,8 @@ extensions = [
 
 # extlinks provides a macro template
 
-extlinks = {'acrn-commit': ('https://github.com/projectacrn/acrn-hypervisor/commit/%s', ''),
-            'acrn-issue': ('https://github.com/projectacrn/acrn-hypervisor/issues/%s', '')
+extlinks = {
+            'acrn-issue': ('https://github.com/projectacrn/acrn-hypervisor/issues/%s', '#')
            }
 
 # use intersphinx linking to link to previous version release notes
@@ -128,7 +128,7 @@ finally:
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/doc/scripts/requirements.txt b/doc/scripts/requirements.txt
index 28fd2d4c4..bb7d0f4e2 100644
--- a/doc/scripts/requirements.txt
+++ b/doc/scripts/requirements.txt
@@ -1,5 +1,5 @@
-breathe>=4.23.0,<=4.31
-sphinx>=3.2.1,<=3.5.4
-docutils==0.16
-sphinx_rtd_theme==1.0
-sphinx-tabs==1.3.0
+breathe>=4.23
+sphinx>=3.2.1,<6.0
+docutils>=0.16,<=0.17.1
+sphinx_rtd_theme==1.0.0
+sphinx-tabs>=1.3.0,<=3.4.0