[SCM] PostGIS branch master updated. 3.7.0rc1-112-g38778320c
git at osgeo.org
git at osgeo.org
Sat Oct 17 00:18:26 PDT 2026
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 38778320c821b872c664ad47d6b0136fc9f81fcf (commit)
via 1bfb16afc99c47121ccb4385ed8e475f6953d15a (commit)
via 3dcb621861ba8549465e1aad97359cd0e71c7161 (commit)
from c3a576e61ddfb7fb2c81edca3a3091183417c432 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 38778320c821b872c664ad47d6b0136fc9f81fcf
Author: Regina Obe <lr at pcorp.us>
Date: Sat Oct 17 03:18:14 2026 -0400
Update release and translation template
diff --git a/doc/po/templates/postgis-manual.pot b/doc/po/templates/postgis-manual.pot
index 5a60449c2..1e6557a8c 100644
--- a/doc/po/templates/postgis-manual.pot
+++ b/doc/po/templates/postgis-manual.pot
@@ -6,7 +6,7 @@ msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: https://bugs.kde.org\n"
-"POT-Creation-Date: 2026-08-04 15:37+0000\n"
+"POT-Creation-Date: 2026-10-17 07:16+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL at ADDRESS>\n"
"Language-Team: LANGUAGE <kde-i18n-doc at kde.org>\n"
@@ -3356,7 +3356,9 @@ msgstr ""
#. Tag: para
#, no-c-format
-msgid ", <xref linkend=\"GetNodeEdges\"/>"
+msgid ""
+", <xref linkend=\"GetNodeEdges\"/> <xref linkend=\"getfaceedges_returntype\"/"
+">"
msgstr ""
#. Tag: refpurpose
@@ -7663,6 +7665,69 @@ msgstr ""
msgid "&sqlmm_compliant; SQL-MM 3: 5.1.8"
msgstr ""
+#. Tag: refpurpose
+#, no-c-format
+msgid "Report locations of self-intersection or self-tangency, if any."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid ""
+"Returns a <varname>simple_detail</varname> row, containing a boolean "
+"(<varname>simple</varname>) stating if a geometry is simple and a geometry "
+"(<varname>location</varname>) pointing out where it is non-simple."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid ""
+"The optional <varname>findAllLocations</varname> parameter can be set to 1 "
+"to report all non-simple locations, rather than just one."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The optional <varname>boundaryNodeRule</varname> values are:"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid ""
+"<code>1</code>: <emphasis role=\"bold\">OGC-Mod2</emphasis> - line endpoints "
+"are in the Boundary if they occur an odd number of times. This is the rule "
+"defined by the OGC SFS standard, and is the default for <function>ST_Relate</"
+"function>."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid ""
+"<code>2</code>: <emphasis role=\"bold\">Endpoint</emphasis> - all endpoints "
+"are in the Boundary."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid ""
+"<code>3</code>: <emphasis role=\"bold\">MultivalentEndpoint</emphasis> - "
+"endpoints are in the Boundary if they occur more than once. In other words, "
+"the boundary is all the \"attached\" or \"inner\" endpoints (but not the "
+"\"unattached/outer\" ones)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid ""
+"<code>4</code>: <emphasis role=\"bold\">MonovalentEndpoint</emphasis> - "
+"endpoints are in the Boundary if they occur only once. In other words, the "
+"boundary is all the \"unattached\" or \"outer\" endpoints."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Availability: 3.7.0"
+msgstr ""
+
#. Tag: refpurpose
#, no-c-format
msgid "Returns the M coordinate of a Point."
@@ -8597,11 +8662,6 @@ msgid ""
"if the input is NULL."
msgstr ""
-#. Tag: para
-#, no-c-format
-msgid "Availability: 3.7.0"
-msgstr ""
-
#. Tag: para
#, no-c-format
msgid "This example extracts control points from a NURBS curve."
@@ -31467,39 +31527,6 @@ msgid ""
"The <varname>boundaryNodeRule</varname> values are:"
msgstr ""
-#. Tag: para
-#, no-c-format
-msgid ""
-"<code>1</code>: <emphasis role=\"bold\">OGC-Mod2</emphasis> - line endpoints "
-"are in the Boundary if they occur an odd number of times. This is the rule "
-"defined by the OGC SFS standard, and is the default for <function>ST_Relate</"
-"function>."
-msgstr ""
-
-#. Tag: para
-#, no-c-format
-msgid ""
-"<code>2</code>: <emphasis role=\"bold\">Endpoint</emphasis> - all endpoints "
-"are in the Boundary."
-msgstr ""
-
-#. Tag: para
-#, no-c-format
-msgid ""
-"<code>3</code>: <emphasis role=\"bold\">MultivalentEndpoint</emphasis> - "
-"endpoints are in the Boundary if they occur more than once. In other words, "
-"the boundary is all the \"attached\" or \"inner\" endpoints (but not the "
-"\"unattached/outer\" ones)."
-msgstr ""
-
-#. Tag: para
-#, no-c-format
-msgid ""
-"<code>4</code>: <emphasis role=\"bold\">MonovalentEndpoint</emphasis> - "
-"endpoints are in the Boundary if they occur only once. In other words, the "
-"boundary is all the \"unattached\" or \"outer\" endpoints."
-msgstr ""
-
#. Tag: para
#, no-c-format
msgid "This function is not in the OGC spec, but is implied. see s2.1.13.2"
@@ -35940,6 +35967,15 @@ msgid ""
"2.3+ is needed. Python 3 is a new requirement to build the documentation."
msgstr ""
+#. Tag: para
+#, no-c-format
+msgid ""
+"Visual examples in the docs are off by default. To build docs with them, "
+"configure with `--with-visual-examples` and make sure you have a running "
+"PostgreSQL instance; they are then generated automatically when building the "
+"docs (or explicitly with `make -C regress visual-examples`)."
+msgstr ""
+
#. Tag: title
#, no-c-format
msgid "Breaking Changes"
@@ -36189,6 +36225,15 @@ msgid ""
"(Darafei Praliaskouski)"
msgstr ""
+#. Tag: para
+#, no-c-format
+msgid ""
+"<link xlink:href=\"https://git.osgeo.org/postgis/postgis/pull/806\">GT-806</"
+"link>, <link xlink:href=\"https://trac.osgeo.org/postgis/"
+"ticket/6124\">#6124</link> --with-visual-examples opt-in configure switch to "
+"build dynamic images (Regina Obe)"
+msgstr ""
+
#. Tag: title
#, no-c-format
msgid "Enhancements"
diff --git a/doc/release_notes.xml b/doc/release_notes.xml
index 2c134e4ae..719e685fa 100644
--- a/doc/release_notes.xml
+++ b/doc/release_notes.xml
@@ -5,9 +5,14 @@
<title>PostGIS 3.7.0</title>
<subtitle>2026/xx/xx</subtitle>
<para>This version requires GEOS 3.10+, PostgreSQL 14-19beta3, Proj 6.1+, and libgmp.
- To take advantage of all postgis extension features, GEOS 3.15+ is needed.
- To take advantage of all postgis_sfcgal extension features SFCGAL 2.3+ is needed.
- Python 3 is a new requirement to build the documentation.</para>
+ To take advantage of all postgis extension features, GEOS 3.15+ is needed.
+ To take advantage of all postgis_sfcgal extension features SFCGAL 2.3+ is needed.
+ Python 3 is a new requirement to build the documentation.</para>
+
+ <para>Visual examples in the docs are off by default. To build docs with them,
+ configure with `--with-visual-examples` and make sure you have a running
+ PostgreSQL instance; they are then generated automatically when building
+ the docs (or explicitly with `make -C regress visual-examples`).</para>
<simplesect>
<title>Breaking Changes</title>
<para><link xlink:href="https://trac.osgeo.org/postgis/ticket/5688">#5688</link>, [topology] topology building functions now interpret tolerance 0 (old default) to really mean 0 and want -1 (new default) to mean "use topology precision" (Sandro Santilli)</para>
@@ -44,6 +49,8 @@
<para><link xlink:href="https://trac.osgeo.org/postgis/ticket/1291">#1291</link>, ST_MakePolygon support for curved rings (Darafei Praliaskouski)</para>
<para><link xlink:href="https://gitea.osgeo.org/postgis/postgis/pulls/270">GT-270</link>, Add NURBSCurve (Loïc Bartoletti)</para>
<para><link xlink:href="https://trac.osgeo.org/postgis/ticket/2863">#2863</link>, Add ST_XSize, ST_YSize, ST_ZSize, and ST_MSize dimension helpers (Darafei Praliaskouski)</para>
+ <para><link xlink:href="https://git.osgeo.org/postgis/postgis/pull/806">GT-806</link>, <link xlink:href="https://trac.osgeo.org/postgis/ticket/6124">#6124</link> --with-visual-examples opt-in
+ configure switch to build dynamic images (Regina Obe)</para>
</simplesect>
<simplesect>
<title>Enhancements</title>
commit 1bfb16afc99c47121ccb4385ed8e475f6953d15a
Author: Regina Obe <lr at pcorp.us>
Date: Sat Oct 17 02:05:25 2026 -0400
Fixes for windows
Closes https://gitea.osgeo.org/postgis/postgis/pulls/806
Closes #6124
diff --git a/NEWS b/NEWS
index 5140c524a..1751d30cc 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,5 @@
-PostGIS 3.7.0
-2026/xx/xx
+PostGIS 3.7.0rc3
+2026/10/xx
This version requires GEOS 3.10+, PostgreSQL 14-19beta3, Proj 6.1+, and libgmp.
To take advantage of all postgis extension features, GEOS 3.15+ is needed.
@@ -28,7 +28,7 @@ the docs (or explicitly with `make -C regress visual-examples`).
- GH-848, CG_AlphaShape now returns a MultiPolygon (Jean Felder)
- [docs] Python 3 and an SVG rasterizer (rsvg-convert preferred,
GraphicsMagick or ImageMagick supported) now required for doc
- building (Darafei Praliaskouski)
+ dynamic image rendering (Darafei Praliaskouski)
* New Features *
@@ -68,6 +68,8 @@ the docs (or explicitly with `make -C regress visual-examples`).
axis to the boundary. (Loïc Bartoletti)
- GH-871, Add CG_PolygonRepair (Loïc Bartoletti)
- GH-872, SFCGAL roof generation algorithms (Loïc Bartoletti)
+ - GT-806, #6124 --with-visual-examples opt-in
+ configure switch to build dynamic images (Regina Obe)
* Enhancements *
diff --git a/ci/winnie/winnie_common.sh b/ci/winnie/winnie_common.sh
index 409bb678c..19795c741 100644
--- a/ci/winnie/winnie_common.sh
+++ b/ci/winnie/winnie_common.sh
@@ -9,7 +9,8 @@ export PROJECTS=/projects
# Don't convert paths
# See https://trac.osgeo.org/postgis/ticket/5436#comment:5
export MSYS2_ARG_CONV_EXCL=/config/tags
-export XML_CATALOG_FILES="/projects/docbook/docbook-5.0.1/catalog.xml"
+export XML_CATALOG_FILES="/projects/dockbook/docbook-xsl/catalog.xml"
+export XLSBASE="/projects/dockbook/docbook-xsl"
if [[ "${OVERRIDE}" == '' ]] ; then
export GEOS_VER=3.15.0
diff --git a/utils/docs/tests/test_postgis_exampletest.py b/utils/docs/tests/test_postgis_exampletest.py
index abf114c58..33eb76da0 100644
--- a/utils/docs/tests/test_postgis_exampletest.py
+++ b/utils/docs/tests/test_postgis_exampletest.py
@@ -21,6 +21,18 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from postgis_exampletest import ExampleTester, QueryRows, parse_source_example
+ at contextlib.contextmanager
+def open_tmp_xml():
+ # Windows denies reopening a NamedTemporaryFile while its delete-on-close
+ # handle is open, so create it with delete=False and unlink it ourselves.
+ handle = tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8", delete=False)
+ try:
+ yield handle
+ finally:
+ handle.close()
+ os.unlink(handle.name)
+
+
def xyz_vertices(points, ring=False):
return [
{"path": [1, index] if ring else [index], "point": point}
@@ -264,7 +276,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -283,7 +295,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -299,7 +311,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -314,7 +326,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -336,7 +348,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -353,7 +365,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -370,7 +382,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
</refsection>
</refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -397,7 +409,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
<screen>1</screen>
</refsection></refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
tester = ExampleTester(source.name)
@@ -445,7 +457,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
<screen>dummy</screen>
</refsection></refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
@@ -465,7 +477,7 @@ SELECT 'POINT(1 2)', $$LINESTRING(0 0,1 1)$$,
<screen>dummy</screen>
</refsection></refentry>
</book>"""
- with tempfile.NamedTemporaryFile("w", suffix=".xml", encoding="utf-8") as source:
+ with open_tmp_xml() as source:
source.write(xml)
source.flush()
example = ExampleTester(source.name).examples()[0]
commit 3dcb621861ba8549465e1aad97359cd0e71c7161
Author: Regina Obe <lr at pcorp.us>
Date: Tue Oct 13 00:34:57 2026 -0400
- By default dynamic image building is turned off
- New configure switch --with-visual-examples is required to enable
dynamic image building.
- Add new switch to doc-building cis and add new make visual example target
- Add conditional WITH_VISUAL_EXAMPLES env to winnie
diff --git a/.woodpecker/docs.yml b/.woodpecker/docs.yml
index 4caca002b..2b2818ead 100644
--- a/.woodpecker/docs.yml
+++ b/.woodpecker/docs.yml
@@ -50,7 +50,7 @@ steps:
commands:
- ./autogen.sh
- mkdir -p build-docs && cd build-docs
- - ../configure --with-pgconfig=/usr/lib/postgresql/18/bin/pg_config --without-protobuf --without-raster
+ - ../configure --with-pgconfig=/usr/lib/postgresql/18/bin/pg_config --without-protobuf --without-raster --with-visual-examples
- make postgis_revision.h
- . ../ci/parallel-jobs.sh
- export POSTGIS_BUILD_JOBS=$$(postgis_ci_parallel_jobs)
diff --git a/NEWS b/NEWS
index aeb7af2aa..5140c524a 100644
--- a/NEWS
+++ b/NEWS
@@ -6,10 +6,10 @@ To take advantage of all postgis extension features, GEOS 3.15+ is needed.
To take advantage of all postgis_sfcgal extension features SFCGAL 2.3+ is needed.
Python 3 is a new requirement to build the documentation.
-To build docs, first run visual examples and make sure you have a running
-PostgreSQL instance.
-
-`make -C regress visual-examples`
+Visual examples in the docs are off by default. To build docs with them,
+configure with `--with-visual-examples` and make sure you have a running
+PostgreSQL instance; they are then generated automatically when building
+the docs (or explicitly with `make -C regress visual-examples`).
* Breaking Changes *
diff --git a/ci/debbie/postgis_release_docs.sh b/ci/debbie/postgis_release_docs.sh
index 91fe4579a..2b90fa1fa 100644
--- a/ci/debbie/postgis_release_docs.sh
+++ b/ci/debbie/postgis_release_docs.sh
@@ -180,6 +180,7 @@ LDFLAGS="-L${SFCGALPATH}/lib -L${PROJPATH}/lib -L${GDALPATH}/lib -L${GEOSPATH}/l
--with-gdalconfig=${GDAL_CONFIG} \
--with-projdir=${PROJPATH} \
--with-sfcgal=${SFCGAL_CONFIG} \
+ --with-visual-examples \
--with-raster \
--htmldir "${HTML_DIR}" \
--docdir "${STUFF_DIR}"
diff --git a/ci/winnie/regress_postgis.sh b/ci/winnie/regress_postgis.sh
index 2c48f998b..107b38f6c 100644
--- a/ci/winnie/regress_postgis.sh
+++ b/ci/winnie/regress_postgis.sh
@@ -70,6 +70,10 @@ if [ "${REGRESS_WITHOUT_RASTER:-0}" == "1" ]; then
EXTRA_CONFIGURE_ARGS="${EXTRA_CONFIGURE_ARGS} --without-raster"
fi
+if [ "${WITH_VISUAL_EXAMPLES:-0}" == "1" ]; then
+ EXTRA_CONFIGURE_ARGS="${EXTRA_CONFIGURE_ARGS} --with-visual-examples"
+fi
+
#CPPFLAGS="-I${PGPATH}/include -I${PROJECTS}/rel-libiconv-${ICON_VER}w${OS_BUILD}${GCC_TYPE}/include" \
#CFLAGS="-Wall -fno-omit-frame-pointer"
diff --git a/ci/winnie/winnie_common.sh b/ci/winnie/winnie_common.sh
index c264be2bc..409bb678c 100644
--- a/ci/winnie/winnie_common.sh
+++ b/ci/winnie/winnie_common.sh
@@ -58,6 +58,10 @@ fi;
echo "LZ4_VER ${LZ4_VER}"
+if [[ "${WITH_VISUAL_EXAMPLES}" == '' ]] ; then
+ export WITH_VISUAL_EXAMPLES=0
+fi;
+
if [[ "${REGRESS_WITHOUT_TOPOLOGY}" == '' ]] ; then
export REGRESS_WITHOUT_TOPOLOGY=0
fi;
diff --git a/configure.ac b/configure.ac
index 7371941f1..8bda1ec8a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -243,9 +243,24 @@ fi
AC_PATH_PROG([PYTHON3], [python3], [])
if test "x$PYTHON3" = "x"; then
AC_MSG_WARN([python3 is not installed so documentation visual examples cannot be generated])
- AC_MSG_WARN([documentation build will fail: run 'make -C regress visual-examples' first])
fi
+dnl Visual examples are rendered from the manual by running the example
+dnl queries against a staged PostGIS build, so they are opt-in.
+VISUAL_EXAMPLES="no"
+AC_ARG_WITH([visual-examples],
+ [AS_HELP_STRING([--with-visual-examples],
+ [Generate visual example images when building the documentation (default is no)])],
+ [], [with_visual_examples="no"])
+
+if test "x$with_visual_examples" != "xno"; then
+ if test "x$PYTHON3" = "x"; then
+ AC_MSG_ERROR([--with-visual-examples requires python3])
+ fi
+ VISUAL_EXAMPLES="yes"
+fi
+AC_SUBST([VISUAL_EXAMPLES])
+
AC_PATH_PROG([XML2POT], [xml2pot], [])
if test "x$XML2POT" = "x"; then
AC_MSG_WARN([xml2pot is not installed so translation template cannot be updated])
@@ -2003,6 +2018,7 @@ if test "x$TOPOLOGY" = "xtopology"; then
else
AC_MSG_RESULT([ PostGIS Topology: disabled])
fi
+AC_MSG_RESULT([ Doc visual examples: ${VISUAL_EXAMPLES}])
if test "x$SFCGAL" = "xsfcgal"; then
AC_MSG_RESULT([ SFCGAL support: enabled])
else
diff --git a/doc/Makefile.in b/doc/Makefile.in
index a0e186e3b..911ff8478 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -50,8 +50,14 @@ DOCSUFFIX=-en
html_builddir=$(abs_builddir)/html
images_builddir=$(html_builddir)/images
pdf_images_builddir=$(abs_builddir)/pdf/images
+VISUAL_EXAMPLES=@VISUAL_EXAMPLES@
+ifeq ($(VISUAL_EXAMPLES),yes)
visual_examples_manifest=$(images_builddir)/visual-examples/manifest.xml
visual_examples_inputs=$(wildcard $(visual_examples_manifest) $(images_builddir)/visual-examples/*.svg)
+else
+visual_examples_manifest=
+visual_examples_inputs=
+endif
ifneq (,$(findstring dev,$(POSTGIS_MICRO_VERSION)))
POSTGIS_DOWNLOAD_URL=https://postgis.net/stuff
@@ -619,11 +625,22 @@ doxygen: doxygen.cfg ## Generate developer's documentation using Doxygen
images: ## Generate images used in html and pdf targets
+images images-install: visual-examples
+
images images-install images-uninstall images-clean:
$(MAKE) -C $(images_builddir) $@
+# With --with-visual-examples, render the examples from a staged build
+# when the manifest is missing; otherwise build without them.
visual-examples:
- @$(if $(shell test -s '$(visual_examples_manifest)' && echo ok),true,$(error Visual examples are missing. Run 'make -C regress visual-examples' first.))
+ifeq ($(VISUAL_EXAMPLES),yes)
+ @if ! test -s '$(visual_examples_manifest)'; then \
+ echo "Generating visual examples..."; \
+ $(MAKE) -C $(top_builddir) visual-examples || exit 1; \
+ fi
+else
+ @true
+endif
pdf-images: visual-examples images
$(MAKE) -C $(images_builddir) $@ PDF_IMAGES_BUILD_DIR="$(pdf_images_builddir)"
@@ -800,7 +817,9 @@ else ifeq ($(XSLTPROC),)
else ifeq ($(XSLBASE),)
@echo "Skipping $@: DocBook XSL stylesheets are not available."
else
- @if ! test -s "$(visual_examples_manifest)"; then \
+ @if test "$(VISUAL_EXAMPLES)" != yes; then \
+ echo "Skipping $@: configure was run without --with-visual-examples."; \
+ elif ! test -s "$(visual_examples_manifest)"; then \
echo "Skipping $@: visual examples are missing. Run 'make -C regress visual-examples' first."; \
else \
$(MAKE) $(html_builddir)/postgis$(DOCSUFFIX)/index.html; \
diff --git a/doc/README b/doc/README
index 04bc08b69..48972e4bd 100644
--- a/doc/README
+++ b/doc/README
@@ -49,7 +49,8 @@ How to
------
Reference figures are generated from executable manual examples. Run
-``make -C regress visual-examples`` before HTML or PDF targets. The staged
+``make -C regress visual-examples`` before HTML or PDF targets (or configure
+with ``--with-visual-examples`` to have the doc targets do it). The staged
PostGIS build supplies geometry paths and raster outputs; the renderer writes
SVG plus a manifest under ``doc/html/images/visual-examples``. HTML embeds the
SVG files directly, while PDF rasterizes the same files as a backend fallback.
diff --git a/doc/development/manual.md b/doc/development/manual.md
index 341e85276..6b3254ddb 100644
--- a/doc/development/manual.md
+++ b/doc/development/manual.md
@@ -62,9 +62,13 @@ renderer. Static raster files under `doc/html/images/static` are limited to
branding and interface icons; the DocBook checker rejects other raster image
references. Use DocBook markup for equations and tables.
-Run the example renderer before an HTML or PDF build:
+Visual examples are off by default. Configure with `--with-visual-examples`
+(requires Python 3 and a running PostgreSQL server) and `make -C doc html` or
+`make -C doc pdf` will render them automatically from a staged build when they
+are missing. They can also be rendered explicitly:
```sh
+./configure --with-visual-examples
make -C regress visual-examples
make -C doc html
make -C doc pdf
diff --git a/doc/html/images/Makefile.in b/doc/html/images/Makefile.in
index 2cdd8e0d6..729e195d3 100644
--- a/doc/html/images/Makefile.in
+++ b/doc/html/images/Makefile.in
@@ -37,6 +37,7 @@ ALL_IMAGES = $(STATIC_IMAGES)
PDF_IMAGES_BUILD_DIR ?= pdf-images
PDF_IMAGES = $(ALL_IMAGES:%=$(PDF_IMAGES_BUILD_DIR)/%)
+VISUAL_EXAMPLES = @VISUAL_EXAMPLES@
VISUAL_EXAMPLES_DIR = visual-examples
VISUAL_EXAMPLES_MANIFEST = $(VISUAL_EXAMPLES_DIR)/manifest.json
VISUAL_EXAMPLES_XML_MANIFEST = $(VISUAL_EXAMPLES_DIR)/manifest.xml
@@ -49,9 +50,14 @@ images: visual-examples-check $(ALL_IMAGES)
pdf-images: $(PDF_IMAGES) visual-examples-pdf
visual-examples-check:
+ifeq ($(VISUAL_EXAMPLES),yes)
@$(if $(shell test -s '$(VISUAL_EXAMPLES_MANIFEST)' && test -s '$(VISUAL_EXAMPLES_XML_MANIFEST)' && echo ok),true,$(error Visual examples are missing. Run 'make -C regress visual-examples' first.))
+else
+ @true
+endif
visual-examples-pdf: visual-examples-check
+ifeq ($(VISUAL_EXAMPLES),yes)
@mkdir -p $(PDF_IMAGES_BUILD_DIR)/$(VISUAL_EXAMPLES_DIR)
@converter=$${POSTGIS_DOC_CONVERTER:-}; rasterizer=convert; \
if test -z "$$converter"; then \
@@ -88,13 +94,18 @@ visual-examples-pdf: visual-examples-check
mv "$$temporary" "$$target"; \
rm -f "$$diagnostics"; \
done
+else
+ @true
+endif
images-install: visual-examples-check $(ALL_IMAGES)
mkdir -p $(DESTDIR)$(htmldir)/images
$(INSTALL_DATA) $(ALL_IMAGES) $(DESTDIR)$(htmldir)/images/
+ifeq ($(VISUAL_EXAMPLES),yes)
mkdir -p $(DESTDIR)$(htmldir)/images/$(VISUAL_EXAMPLES_DIR)
$(INSTALL_DATA) $(VISUAL_EXAMPLES_DIR)/*.svg $(VISUAL_EXAMPLES_MANIFEST) $(VISUAL_EXAMPLES_XML_MANIFEST) \
$(DESTDIR)$(htmldir)/images/$(VISUAL_EXAMPLES_DIR)/
+endif
images-uninstall:
rm -f $(ALL_IMAGES:%=$(DESTDIR)$(htmldir)/images/%)
diff --git a/doc/installation.xml b/doc/installation.xml
index da7ff43e2..6fd5fac54 100644
--- a/doc/installation.xml
+++ b/doc/installation.xml
@@ -322,7 +322,8 @@ sh autogen.sh
<listitem>
<para>
- Python 3 is required to run the manual example tester that generates
+ Python 3 is required, when configured with
+ <command>--with-visual-examples</command> (off by default), to run the manual example tester that generates
the visual examples which the HTML and PDF documentation embed.
The examples are executed against a live PostgreSQL server running the
staged PostGIS build via <command>make -C regress visual-examples</command>;
-----------------------------------------------------------------------
Summary of changes:
.woodpecker/docs.yml | 2 +-
NEWS | 16 ++--
ci/debbie/postgis_release_docs.sh | 1 +
ci/winnie/regress_postgis.sh | 4 +
ci/winnie/winnie_common.sh | 7 +-
configure.ac | 18 +++-
doc/Makefile.in | 23 ++++-
doc/README | 3 +-
doc/development/manual.md | 6 +-
doc/html/images/Makefile.in | 11 +++
doc/installation.xml | 3 +-
doc/po/templates/postgis-manual.pot | 125 ++++++++++++++++++---------
doc/release_notes.xml | 13 ++-
utils/docs/tests/test_postgis_exampletest.py | 32 ++++---
14 files changed, 196 insertions(+), 68 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list