DOC: Use breathe>=4.27 to support Doxygen \page, \section, etc.

5 files changed, 7 insertions, 159 deletions

diff --git a/.gitignore b/.gitignore
index 1d9aa793..b15e8ce5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -96,7 +96,6 @@ install_manifest.txt
 /data/for_tests/
 
 # docs
-tmp_breathe
 /docs/.doxygen_up_to_date
 /docs/build
 /latex
diff --git a/docs/Makefile b/docs/Makefile
index 22399302..15a1ca2a 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -32,9 +32,6 @@ html: .doxygen_up_to_date
 	# Undoes the hack done in scripts/doxygen.sh
 	@sed "s/io::Convention_/io::Convention/g" < $(BUILDDIR)/html/development/reference/cpp/io.html | sed "s/>Convention_/>Convention/g" | sed "s/_WKT2/WKT2/g" | sed "s/_WKT1/WKT1/g" > $(BUILDDIR)/html/development/reference/cpp/io.html.tmp
 	@mv $(BUILDDIR)/html/development/reference/cpp/io.html.tmp $(BUILDDIR)/html/development/reference/cpp/io.html
-	# Undoes the hacks of scripts/generate_breathe_friendly_general_doc.py
-	@sed "s/<em class=\"property\">namespace <\/em>//g" < $(BUILDDIR)/html/development/reference/cpp/cpp_general.html > $(BUILDDIR)/html/development/reference/cpp/cpp_general.html.tmp
-	@mv $(BUILDDIR)/html/development/reference/cpp/cpp_general.html.tmp $(BUILDDIR)/html/development/reference/cpp/cpp_general.html
 	@cp -r ../schemas $(BUILDDIR)/html/schemas
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/docs/source/development/reference/cpp/cpp_general.rst b/docs/source/development/reference/cpp/cpp_general.rst
index d54daaa8..4d27814f 100644
--- a/docs/source/development/reference/cpp/cpp_general.rst
+++ b/docs/source/development/reference/cpp/cpp_general.rst
@@ -3,5 +3,5 @@
 General documentation
 ---------------------
 
-.. doxygenfile:: general_doc.dox.reworked.h
+.. doxygenpage:: general_doc
    :project: doxygen_api
diff --git a/scripts/doxygen.sh b/scripts/doxygen.sh
index f169c78e..517447d2 100755
--- a/scripts/doxygen.sh
+++ b/scripts/doxygen.sh
@@ -29,41 +29,23 @@ else
     echo "No Doxygen warnings found";
 fi
 
+if test $(doxygen --version) = "1.8.17" ; then
+    echo "Doxygen 1.8.17 is incompatible" && /bin/false;
+fi
 
-# XML generation (for Breathe)
-mkdir -p docs/build/tmp_breathe
-python scripts/generate_breathe_friendly_general_doc.py
 rm -rf docs/build/xml/
 
-# Ugly hack to workaround a bug of Doxygen 1.8.17 that erroneously detect proj_network_get_header_value_cbk_type/ as a variable
-sed "s/const char\* (\*proj_network_get_header_value_cbk_type/CONST_CHAR\* (\*proj_network_get_header_value_cbk_type/" < src/proj.h > docs/build/tmp_breathe/proj.h
-
-(cat Doxyfile; printf "GENERATE_HTML=NO\nGENERATE_XML=YES\nINPUT= src/iso19111 src/iso19111/operation include/proj docs/build/tmp_breathe/proj.h src/filemanager.cpp src/networkfilemanager.cpp docs/build/tmp_breathe/general_doc.dox.reworked.h") | doxygen -  > docs/build/tmp_breathe/docs_log.txt 2>&1
-if grep -i warning docs/build/tmp_breathe/docs_log.txt; then
-    echo "Doxygen warnings found" && cat docs/build/tmp_breathe/docs_log.txt && /bin/false;
+(cat Doxyfile; printf "GENERATE_HTML=NO\nGENERATE_XML=YES\nINPUT= src/iso19111 src/iso19111/operation include/proj src/proj.h src/filemanager.cpp src/networkfilemanager.cpp src/general_doc.dox") | doxygen -  > docs/build/docs_log.txt 2>&1
+if grep -i warning docs/build/docs_log.txt; then
+    echo "Doxygen warnings found" && cat docs/build/docs_log.txt && /bin/false;
 else
     echo "No Doxygen warnings found";
 fi
 
-for i in ${TOPDIR}/docs/build/xml/*; do
-
-# Fix Breathe error on Doxygen XML
-# Type must be either just a name or a typedef-like declaration.
-#   If just a name:
-#     Invalid definition: Expected end of definition. [error at 32]
-#       osgeo::proj::common::MeasurePtr = typedef std::shared_ptr<Measure>
-    sed "s/ = typedef /=/g" < $i > $i.tmp;
-    mv $i.tmp $i
-done
-
 # There is a confusion for Breathe between PROJStringFormatter::Convention and WKTFormatter:Convention
 sed "s/Convention/Convention_/g" < ${TOPDIR}/docs/build/xml/classosgeo_1_1proj_1_1io_1_1WKTFormatter.xml | sed "s/WKT2_2018/_WKT2_2018/g" | sed "s/WKT2_2019/_WKT2_2019/g" | sed "s/WKT2_2015/_WKT2_2015/g" | sed "s/WKT1_GDAL/_WKT1_GDAL/g" | sed "s/WKT1_ESRI/_WKT1_ESRI/g" > ${TOPDIR}/docs/build/xml/classosgeo_1_1proj_1_1io_1_1WKTFormatter.xml.tmp
 mv ${TOPDIR}/docs/build/xml/classosgeo_1_1proj_1_1io_1_1WKTFormatter.xml.tmp  ${TOPDIR}/docs/build/xml/classosgeo_1_1proj_1_1io_1_1WKTFormatter.xml
 
-# Ugly hack to workaround a bug of Doxygen 1.8.17 that erroneously detect proj_network_get_header_value_cbk_type/ as a variable
-sed "s/CONST_CHAR/const char/"  < ${TOPDIR}/docs/build/xml/proj_8h.xml > ${TOPDIR}/docs/build/xml/proj_8h.xml.tmp
-mv ${TOPDIR}/docs/build/xml/proj_8h.xml.tmp ${TOPDIR}/docs/build/xml/proj_8h.xml
-
 # Hack for Breathe 4.17.0 issue that is confused by osgeo::proj::common::UnitOfMeasure::Type::NONE (enumeration value of Type) and osgeo::proj::common::UnitOfMeasure::NONE (member value), whereas 4.16.0 works fine.
 # Filed as https://github.com/michaeljones/breathe/issues/518
 sed "s/          <name>NONE<\/name>/          <name>Type::NONE<\/name>/"  < ${TOPDIR}/docs/build/xml/classosgeo_1_1proj_1_1common_1_1UnitOfMeasure.xml > ${TOPDIR}/docs/build/xml/classosgeo_1_1proj_1_1common_1_1UnitOfMeasure.xml.tmp
diff --git a/scripts/generate_breathe_friendly_general_doc.py b/scripts/generate_breathe_friendly_general_doc.py
deleted file mode 100644
index 746bdd04..00000000
--- a/scripts/generate_breathe_friendly_general_doc.py
+++ /dev/null
@@ -1,130 +0,0 @@
-#!/usr/bin/env python
-###############################################################################
-# $Id$
-#
-#  Project:  PROJ
-#  Purpose:  Rework general_doc.dox in a Breathe friendly (hacky) way
-#  Author:   Even Rouault <even.rouault at spatialys.com>
-#
-###############################################################################
-#  Copyright (c) 2018, Even Rouault <even.rouault at spatialys.com>
-#
-#  Permission is hereby granted, free of charge, to any person obtaining a
-#  copy of this software and associated documentation files (the "Software"),
-#  to deal in the Software without restriction, including without limitation
-#  the rights to use, copy, modify, merge, publish, distribute, sublicense,
-#  and/or sell copies of the Software, and to permit persons to whom the
-#  Software is furnished to do so, subject to the following conditions:
-#
-#  The above copyright notice and this permission notice shall be included
-#  in all copies or substantial portions of the Software.
-#
-#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-#  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-#  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-#  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-#  DEALINGS IN THE SOFTWARE.
-###############################################################################
-
-import os
-
-# HACK HACK HACK
-# Transform a .dox with section, subsection, etc.. in fake namespaces
-# since Breathe cannot handle such sections and references to them
-
-script_dir_name = os.path.dirname(os.path.realpath(__file__))
-general_doc_dox = os.path.join(os.path.dirname(
-    script_dir_name), 'src', 'general_doc.dox')
-general_doc_dox_reworked_h = os.path.join(os.path.dirname(
-    script_dir_name), 'docs/build/tmp_breathe', 'general_doc.dox.reworked.h')
-
-out = open(general_doc_dox_reworked_h, 'wt')
-
-
-class Section:
-
-    def __init__(self):
-        self.name = None
-        self.title = None
-        self.content = ''
-        self.children = []
-        pass
-
-    def serialize(self, out):
-        out.write("/** \\brief %s\n" % self.title)
-        out.write("\n")
-        out.write("%s\n" % self.content)
-        out.write("*/\n")
-        out.write("namespace %s {\n" % self.name)
-        out.write("}\n")
-        for child in self.children:
-            child.serialize(out)
-
-
-stack = []
-current = None
-
-for line in open(general_doc_dox, 'rt').readlines():
-    line = line.strip()
-    if line == '/*!' or line == '*/':
-        continue
-
-    if line.startswith('\page'):
-
-        tokens = line.split(' ')
-        new = Section()
-        new.name = tokens[1]
-        new.title = ' '.join(tokens[2:])
-        current = new
-        stack.append(new)
-        continue
-
-    if line.startswith('\section'):
-
-        stack = stack[0:1]
-        current = stack[-1]
-
-        tokens = line.split(' ')
-        new = Section()
-        new.name = tokens[1]
-        new.title = ' '.join(tokens[2:])
-        current.children.append(new)
-        current = new
-        stack.append(new)
-        continue
-
-    if line.startswith('\subsection'):
-
-        stack = stack[0:2]
-        current = stack[-1]
-
-        tokens = line.split(' ')
-        new = Section()
-        new.name = tokens[1]
-        new.title = ' '.join(tokens[2:])
-        current.children.append(new)
-        current = new
-        stack.append(new)
-        continue
-
-    if line.startswith('\subsubsection'):
-
-        stack = stack[0:3]
-        current = stack[-1]
-
-        tokens = line.split(' ')
-        new = Section()
-        new.name = tokens[1]
-        new.title = ' '.join(tokens[2:])
-        current.children.append(new)
-        current = new
-        stack.append(new)
-        continue
-
-    if current:
-        current.content += line + '\n'
-
-for child in stack[0].children:
-    child.serialize(out)