From b4938231920eaa9cfee5f5dd97248eea18bf64b8 Mon Sep 17 00:00:00 2001
From: Axel Huebl <axel.huebl@plasma.ninja>
Date: Fri, 22 Oct 2021 09:47:11 -0700
Subject: [PATCH] Docs: Tagfile (Doxygen) (#2463)

* Docs: Tagfile (Doxygen)

Generate a tagfile.
Used as anchor in external projects.

* Doxygen Interlink: External AMReX Tagfile

Link AMReX objects to the AMReX doxygen page via its latest
Doxygen tagfile.
---
 .gitignore          |  1 +
 Docs/Doxyfile       |  7 ++++---
 Docs/source/conf.py | 10 ++++++++--
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/.gitignore b/.gitignore
index a83c9170a65..eaae585d299 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,7 @@ Python/pywarpx.egg-info/
 ##########
 # Sphinx #
 ##########
+Docs/amrex-doxygen-web.tag.xml
 Docs/doxyhtml/
 Docs/doxyxml/
 Docs/source/_static/
diff --git a/Docs/Doxyfile b/Docs/Doxyfile
index 42df37ee68c..9ff34185a9f 100644
--- a/Docs/Doxyfile
+++ b/Docs/Doxyfile
@@ -328,7 +328,8 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+# TAGFILES += "cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -2103,13 +2104,13 @@ SKIP_FUNCTION_MACROS   = YES
 # the path). If a tag file is not located in the directory in which doxygen is
 # run, you must also specify the path to the tagfile here.
 
-TAGFILES               =
+TAGFILES               = amrex-doxygen-web.tag.xml=https://amrex-codes.github.io/amrex/doxygen/
 
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create a
 # tag file that is based on the input files it reads. See section "Linking to
 # external documentation" for more information about the usage of tag files.
 
-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = warpx-doxygen-web.tag.xml
 
 # If the ALLEXTERNALS tag is set to YES, all external class will be listed in
 # the class index. If set to NO, only the inherited external classes will be
diff --git a/Docs/source/conf.py b/Docs/source/conf.py
index 07cfb7ea70f..ba2f69b6ed1 100644
--- a/Docs/source/conf.py
+++ b/Docs/source/conf.py
@@ -25,7 +25,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os, sys, subprocess
+import os, sys, urllib.request, subprocess
 import sphinx_rtd_theme
 sys.path.insert(0, os.path.join( os.path.abspath(__file__), '../Python') )
 
@@ -58,7 +58,7 @@
 
 # General information about the project.
 project = 'WarpX'
-copyright = '2017, WarpX collaboration'
+copyright = '2017-2021, WarpX collaboration'
 author = 'WarpX collaboration'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -183,4 +183,10 @@
 # Tell sphinx what the pygments highlight language should be.
 highlight_language = 'cpp'
 
+# Download AMReX Doxygen Tagfile to interlink Doxygen docs
+url = 'https://amrex-codes.github.io/amrex/docs_xml/doxygen/amrex-doxygen-web.tag.xml'
+urllib.request.urlretrieve(url, '../amrex-doxygen-web.tag.xml')
+
+
+# Build Doxygen
 subprocess.call('cd ../; doxygen; mkdir -p source/_static; cp -r doxyhtml source/_static/', shell=True)