diff --git a/docs/source/background.rst b/docs/source/background.rst
index 7841f296..2aec81a5 100644
--- a/docs/source/background.rst
+++ b/docs/source/background.rst
@@ -39,22 +39,24 @@ Originally developed in the mid-1990's at the University of Minnesota,
MapServer is released under an MIT-style license, and runs on all major
platforms (Windows, Linux, Mac OS X).
Mapserver services are defined by `Mapfiles `_,
-which can be generated by |short_name|.
+which can be generated by |short_name|, but support for it is limited.
`GeoNetwork `_ is a catalog for registering
-assets, such as spatial datasets. It contains a CatalogService for the Web (CSW)
+assets, such as spatial datasets. It contains a Catalog Service for the Web (CSW)
endpoint. GeoNetwork can operate on various metadata models via a plugin mechanism. It
supports ISO19115-3, ISO19139, ISO19110 and DCAT metadata standards. GeoNetwork
opensource software complies with the requirements of INSPIRE discovery services and metadata.
-`GeoStyler `_ is a JS library used in the `Shogun framework `_
-to create generic styles. GeoServer also has a `plugin `_
-that allows to style layers using GeoStyler. |short_name| does not make use of the GeoStyler library, but it does use the GeoStyler format
-internally as an intermediate format, which can be exported as a GeoStyler style file (JSON).
+`GeoStyler `_ is a NodeJS tool by Terrestris to create map styles.
+GeoServer also has a `plugin `_
+that allows users to style layers using GeoStyler. Although |short_name| does not make use of GeoStyler directly,
+it does use the Python-based `bridge-style `_ library, that utilizes
+GeoStyler JSON as an intermediate format before it converts it to various other formats (SLD, Mapfile, etc.).
`Mapbox Style `_ is a style format that defines the visual
appearance of vector tiles in the `Mapbox JavaScript API `_.
-|short_name| is able to generate a Mapbox style document.
+|short_name| is able to generate a Mapbox or `MapLibre `_ style document, but newer versions
+of both specifications may not be fully compatible anymore.
`PostGIS `_ is a spatial extension to the popular open source Postgres database.
|short_name| is able to export any local data to a remote (or local) PostGIS database, allowing it
diff --git a/docs/source/bridge_dialog.rst b/docs/source/bridge_dialog.rst
index 2396e9d5..696e0fef 100644
--- a/docs/source/bridge_dialog.rst
+++ b/docs/source/bridge_dialog.rst
@@ -25,14 +25,15 @@ Logging and error handling
| This panel can be opened by clicking the "balloon" button in the lower-right corner of QGIS
or by checking the :guilabel:`View` > :guilabel:`Panels` > :guilabel:`Log Messages` item from the QGIS menu bar.
-| In some (rare) occasions, |short_name| might raise an exception. When this happens, a dialog pops up with a Python stack trace.
-| If the error re-occurs, please press the :guilabel:`Send Report` button, so that we're aware of the issue and can try fixing it.
+In some (rare) occasions, |short_name| might raise an exception. When this happens, a dialog pops up with a Python stack trace.
+If you keep experiencing the same error, please press the :guilabel:`Send Report` button. This will open your browser with a web form,
+where you can (optionally) describe the problem and send the error report to the |short_name| developers, so they are aware and can fix it.
Internationalization (i18n)
---------------------------
|app_name| is primarily targeted towards an international audience, which means that it has an English user interface.
-| However, some basic translations are available for the following languages:
+However, some basic translations are available for the following languages:
- Dutch (Nederlands)
- German (Deutsch)
@@ -40,3 +41,5 @@ Internationalization (i18n)
| The translations will be applied automatically based on the language settings of the user.
If no translation can be found for a certain text, the original text (English) will be displayed instead.
+
+If you would like to contribute to the translations, please join the |short_name| `Transifex project `_.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ba7b1daf..3a23e66d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -136,12 +136,12 @@
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-html_logo = str(src_dir.parent.resolve() / 'themes/geocat_rtd/static/bridge.svg')
+html_logo = './img/bridge_logo.svg'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
-html_favicon = str(src_dir.parent.resolve() / 'themes/geocat_rtd/static/favicon.ico')
+html_favicon = './img/favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
diff --git a/docs/source/img/bridge_logo.svg b/docs/source/img/bridge_logo.svg
new file mode 100644
index 00000000..fb20ae70
--- /dev/null
+++ b/docs/source/img/bridge_logo.svg
@@ -0,0 +1,26 @@
+
diff --git a/docs/source/img/favicon.ico b/docs/source/img/favicon.ico
new file mode 100644
index 00000000..26302c14
Binary files /dev/null and b/docs/source/img/favicon.ico differ
diff --git a/docs/source/img/loadmetadata.png b/docs/source/img/loadmetadata.png
deleted file mode 100644
index b556df8f..00000000
Binary files a/docs/source/img/loadmetadata.png and /dev/null differ
diff --git a/docs/source/img/manually_load_metadata.png b/docs/source/img/manually_load_metadata.png
index 90504cfd..bb029671 100644
Binary files a/docs/source/img/manually_load_metadata.png and b/docs/source/img/manually_load_metadata.png differ
diff --git a/docs/source/img/preview_metadata_button.png b/docs/source/img/preview_metadata_button.png
deleted file mode 100644
index f77f5f5f..00000000
Binary files a/docs/source/img/preview_metadata_button.png and /dev/null differ
diff --git a/docs/source/img/publish_layers_context_menu.png b/docs/source/img/publish_layers_context_menu.png
index d3626750..33f29e83 100644
Binary files a/docs/source/img/publish_layers_context_menu.png and b/docs/source/img/publish_layers_context_menu.png differ
diff --git a/docs/source/img/publish_layers_list.png b/docs/source/img/publish_layers_list.png
index a1ef2ac5..a5d359f6 100644
Binary files a/docs/source/img/publish_layers_list.png and b/docs/source/img/publish_layers_list.png differ
diff --git a/docs/source/img/publish_layers_progress.png b/docs/source/img/publish_layers_progress.png
index 884b888d..3252a9fb 100644
Binary files a/docs/source/img/publish_layers_progress.png and b/docs/source/img/publish_layers_progress.png differ
diff --git a/docs/source/img/publish_layers_report.png b/docs/source/img/publish_layers_report.png
index 6f39578a..4bb8220d 100644
Binary files a/docs/source/img/publish_layers_report.png and b/docs/source/img/publish_layers_report.png differ
diff --git a/docs/source/img/publish_section.png b/docs/source/img/publish_section.png
index a51abb4f..b52a7d02 100644
Binary files a/docs/source/img/publish_section.png and b/docs/source/img/publish_section.png differ
diff --git a/docs/source/img/publish_workspace_warning.png b/docs/source/img/publish_workspace_warning.png
index 4d69c26c..036d7e88 100644
Binary files a/docs/source/img/publish_workspace_warning.png and b/docs/source/img/publish_workspace_warning.png differ
diff --git a/docs/source/img/quickstart_authentication.png b/docs/source/img/quickstart_authentication.png
index a8fe7664..e653c892 100644
Binary files a/docs/source/img/quickstart_authentication.png and b/docs/source/img/quickstart_authentication.png differ
diff --git a/docs/source/img/quickstart_newgeoserver.png b/docs/source/img/quickstart_newgeoserver.png
index b7301e98..3bf421b0 100644
Binary files a/docs/source/img/quickstart_newgeoserver.png and b/docs/source/img/quickstart_newgeoserver.png differ
diff --git a/docs/source/img/quickstart_publishexample.png b/docs/source/img/quickstart_publishexample.png
index 9185ae10..a405df4c 100644
Binary files a/docs/source/img/quickstart_publishexample.png and b/docs/source/img/quickstart_publishexample.png differ
diff --git a/docs/source/img/quickstart_publishprogress.png b/docs/source/img/quickstart_publishprogress.png
deleted file mode 100644
index 22a8a276..00000000
Binary files a/docs/source/img/quickstart_publishprogress.png and /dev/null differ
diff --git a/docs/source/img/quickstart_publishresult.png b/docs/source/img/quickstart_publishresult.png
deleted file mode 100644
index 187b6f88..00000000
Binary files a/docs/source/img/quickstart_publishresult.png and /dev/null differ
diff --git a/docs/source/img/quickstart_titleabstract.png b/docs/source/img/quickstart_titleabstract.png
index f986234c..5180d632 100644
Binary files a/docs/source/img/quickstart_titleabstract.png and b/docs/source/img/quickstart_titleabstract.png differ
diff --git a/docs/source/img/quickstart_wmspreview.png b/docs/source/img/quickstart_wmspreview.png
deleted file mode 100644
index df345053..00000000
Binary files a/docs/source/img/quickstart_wmspreview.png and /dev/null differ
diff --git a/docs/source/img/servers.png b/docs/source/img/servers.png
deleted file mode 100644
index afd714dd..00000000
Binary files a/docs/source/img/servers.png and /dev/null differ
diff --git a/docs/source/img/servers_geonetwork.png b/docs/source/img/servers_geonetwork.png
index a2d2885e..252ea70f 100644
Binary files a/docs/source/img/servers_geonetwork.png and b/docs/source/img/servers_geonetwork.png differ
diff --git a/docs/source/img/servers_geoserver.png b/docs/source/img/servers_geoserver.png
index 69d35043..43e69a80 100644
Binary files a/docs/source/img/servers_geoserver.png and b/docs/source/img/servers_geoserver.png differ
diff --git a/docs/source/img/servers_geoserver2.png b/docs/source/img/servers_geoserver2.png
index bc407ee7..c0d33eb3 100644
Binary files a/docs/source/img/servers_geoserver2.png and b/docs/source/img/servers_geoserver2.png differ
diff --git a/docs/source/img/servers_mapserver.png b/docs/source/img/servers_mapserver.png
index 5d4d2535..4d86d97c 100644
Binary files a/docs/source/img/servers_mapserver.png and b/docs/source/img/servers_mapserver.png differ
diff --git a/docs/source/img/servers_mapserver2.png b/docs/source/img/servers_mapserver2.png
index 70dadcbe..8482ef60 100644
Binary files a/docs/source/img/servers_mapserver2.png and b/docs/source/img/servers_mapserver2.png differ
diff --git a/docs/source/img/servers_postgis.png b/docs/source/img/servers_postgis.png
index bcb39ebf..5e78bc04 100644
Binary files a/docs/source/img/servers_postgis.png and b/docs/source/img/servers_postgis.png differ
diff --git a/docs/source/img/validation.png b/docs/source/img/validation.png
deleted file mode 100644
index 49cde75d..00000000
Binary files a/docs/source/img/validation.png and /dev/null differ
diff --git a/docs/source/publish.rst b/docs/source/publish.rst
index cd591328..5206c1d1 100644
--- a/docs/source/publish.rst
+++ b/docs/source/publish.rst
@@ -62,7 +62,7 @@ or specify the things you wish to export to a local file on the :guilabel:`Offli
When publishing online, you can publish your layers to a geodata server, their metadata to a metadata server, or both in one go.
Those servers must be selected from the two available drop-down lists in the :guilabel:`Online` tab.
-As mentioned before, these servers should be added beforehand in the :guilabel:`Servers` section of the |short_name| dialog,
+As mentioned before, these servers should be added beforehand in the :guilabel:`Connections` section of the |short_name| dialog,
as described in :ref:`ServerConnections`.
.. note:: If you are publishing layers to GeoServer, the destination workspace name will be taken from the
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
index f5079e4f..87c245cc 100644
--- a/docs/source/quickstart.rst
+++ b/docs/source/quickstart.rst
@@ -1,6 +1,8 @@
Quickstart Tutorial
###################
+ .. |nbsp| unicode:: 0xA0
+
Once |app_name| has been :ref:`installed `, the first thing you might want to do is publish some layers!
This quickstart tutorial will walk you through the process of publishing a QGIS map layers to GeoServer.
@@ -35,7 +37,11 @@ following panel:
Step 3: add new connection
--------------------------
-Click the :guilabel:`Add...` button on the lower left corner of the :guilabel:`Connections` panel and select :guilabel:`GeoServer`:
+.. |addbutton| image:: ../../geocatbridge/images/add.svg
+ :height: 16 px
+ :width: 16 px
+
+Click the |addbutton| **Add...** button on the lower left corner of the :guilabel:`Connections` panel and select :guilabel:`GeoServer`:
.. image:: ./img/quickstart_newserver.png
@@ -71,7 +77,7 @@ Step 6: add new credentials
---------------------------
In order to actually establish a connection, we need to authenticate ourselves with GeoServer.
-To do that, add new :guilabel:`Credentials` by clicking the :guilabel:`+` button:
+To do that, add new :guilabel:`Credentials` by clicking the |addbutton| button:
.. image:: ./img/quickstart_addauth.png
@@ -80,7 +86,7 @@ If you have already set GeoServer credentials before, you may select the right o
Step 7: authentication details
------------------------------
-After you clicked the :guilabel:`+` button in the previous step, the *Authentication* dialog will pop up.
+After you clicked the |addbutton| button in the previous step, the *Authentication* dialog will pop up.
For the authentication mechanism, we will use *Basic authentication*. This is the default and works
well with GeoServer. It also is the only mechanism that |short_name| currently supports.
@@ -144,7 +150,7 @@ In the :guilabel:`Online` tab at the bottom of the :guilabel:`Publish` panel, se
.. image:: ./img/quickstart_setdataserver.png
-The :guilabel:`Data server` list should display all the names of the configurations that you created in the :guilabel:`Servers` panel.
+The :guilabel:`Data server` list should display all the names of the configurations that you created in the :guilabel:`Connections` panel.
If you just got started, then there will likely only be 1 item in this list.
Step 3: select layers
@@ -160,6 +166,8 @@ the layer name as shown in the QGIS Table of Contents is used.
.. image:: ./img/quickstart_titleabstract.png
+|nbsp|
+
.. tip:: If you have vector layers with lots of attributes, but you only need to publish a couple of these
fields, you can select the applicable layer and click on the :guilabel:`Attributes` tab.
Here you can uncheck all attributes that do *not* need to be published, which will save some storage
@@ -173,7 +181,9 @@ For this tutorial, we will simply go ahead and publish **all layers**. As noted
Click the :guilabel:`Publish` button in the lower right corner of the |short_name| dialog to start the publication process.
During this process, a progress dialog should appear:
- .. image:: ./img/quickstart_publishprogress.png
+ .. image:: ./img/publish_layers_progress.png
+
+|nbsp|
.. note:: For you (the user) it may seem that |short_name| does not treat *raster* layers differently from *vector* layers.
Under the hood however, |short_name| will **always** publish *raster* data to a file-based GeoServer datastore
@@ -185,10 +195,14 @@ Step 5: review results
Once the publish process has completed, a result dialog should appear:
- .. image:: ./img/quickstart_publishresult.png
+ .. image:: ./img/publish_layers_report.png
+
+.. |attnbutton| image:: ../../geocatbridge/images/attention.svg
+ :height: 16 px
+ :width: 16 px
If there are any errors or warnings, these are shown in the :guilabel:`Status` column of the published layer list.
-Click on the tiny :guilabel:`!` buttons to get more details about the issue(s).
+Click on the tiny |attnbutton| buttons to get more details about the issue(s).
If there are no issues, it should say *OK* next to each layer.
Close the result dialog once you finished reviewing.
@@ -209,7 +223,7 @@ If you wish to view a browser-based preview of the GeoServer WMS, you can right-
icon and choose either :guilabel:`View all WMS layers` to preview all layers (i.e. the entire map) in your
GeoServer workspace, or choose :guilabel:`View this WMS layer` to only preview the selected layer:
- .. image:: ./img/quickstart_wmspreview.png
+ .. image:: ./img/publish_layers_context_menu.png
The OpenLayers preview for all layers could for example look like this:
diff --git a/docs/source/server_configuration.rst b/docs/source/server_configuration.rst
index a3e580f7..d925a30a 100644
--- a/docs/source/server_configuration.rst
+++ b/docs/source/server_configuration.rst
@@ -6,13 +6,17 @@ Server Connections
Before you can publish data with |app_name|, you will have to configure one or more server connections.
This can be achieved in the :guilabel:`Connections` section of the |short_name| dialog:
-.. image:: ./img/servers.png
+.. image:: ./img/quickstart_servers.png
Adding connections
##################
-Click :guilabel:`Add...` and choose one of the supported server types to create a new server connection:
+.. |addbutton| image:: ../../geocatbridge/images/add.svg
+ :height: 16 px
+ :width: 16 px
+
+Click |addbutton| **Add...** and choose one of the supported server types to create a new server connection:
- GeoServer
- MapServer
@@ -22,14 +26,30 @@ Click :guilabel:`Add...` and choose one of the supported server types to create
| Fill in the required parameters and click the :guilabel:`Save` button to store the connection details.
| You can edit the parameters of a server at any given time. Just select the server connection in the left panel, and edit the fields you wish to change in the right panel.
-If you wish to remove a server connection, select it from the left panel and click the :guilabel:`Remove` button.
-The :guilabel:`Duplicate` button may come in handy if you wish to try out an alternative configuration based on an existing
+.. |removebutton| image:: ../../geocatbridge/images/remove.svg
+ :height: 16 px
+ :width: 16 px
+
+.. |duplicatebutton| image:: ../../geocatbridge/images/duplicate.svg
+ :height: 16 px
+ :width: 16 px
+
+If you wish to remove a server connection, select it from the left panel and click the |removebutton| **Remove** button.
+The |duplicatebutton| **Duplicate** button may come in handy if you wish to try out an alternative configuration based on an existing
server connection.
+.. |exportbutton| image:: ../../geocatbridge/images/export.svg
+ :height: 16 px
+ :width: 16 px
+
+.. |importbutton| image:: ../../geocatbridge/images/import.svg
+ :height: 16 px
+ :width: 16 px
+
| |short_name| will automatically store all server connections in the QGIS settings for later use.
-| However, sometimes you might want to backup or share all the configured server connections. The :guilabel:`Export` button will
+| However, sometimes you might want to backup or share all the configured server connections. The |exportbutton| **Export** button will
allow you to *save* a JSON file of the current configuration.
-| The :guilabel:`Import` button will do the opposite and *load* server connections from a JSON file. Note that the imported connections will be
+| The |importbutton| **Import** button will do the opposite and *load* server connections from a JSON file. Note that the imported connections will be
*added* to the list (i.e. no existing connections will be removed). |short_name| will append a numeric suffix to server connections
with a name that already exists.
@@ -77,42 +97,74 @@ after all layers were successfully published to GeoServer.
Click :guilabel:`Test Connection` to verify that the connection can be established.
-You should also specify how layer data will be stored on the server. Three different methods are available:
+You also need to specify how the layer data should be stored. Three different storage methods are available:
+
+1. `File-based storage`_
+2. `Import into PostGIS database (direct connect)`_ (vector layers only)
+3. `Import into PostGIS database (managed by GeoServer)`_ (vector layers only)
+
File-based storage
^^^^^^^^^^^^^^^^^^
-| The layer data is uploaded and stored as files in the GeoServer target workspace on the server.
+| The layer data is uploaded and stored as files in the GeoServer target workspace datastore.
| |short_name| prefers to upload vector data as GeoPackages and raster data as GeoTIFF files.
+This method is the most straight-forward and should always work, as there are no dependencies.
+However, depending on the size of the data, this method may be slower and could potentially fail due to network timeouts
+or server-side file upload size limitations.
+
.. _PostGISDirectOption:
Import into PostGIS database (direct connect)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-| The layer data is uploaded to tables in a PostGIS database directly (i.e. by |short_name|, see `PostGIS`_).
-| GeoServer will *not* handle the database upload, but merely establish a link to the database table in the created layer(s). This will require a direct PostGIS connection, which you can set up in the *Servers* section of |short_name| as well (see below).
-| Note that GeoServer should also have read access to that PostGIS connection.
+| The layer data is imported by |short_name| into a PostGIS database directly.
+| GeoServer will merely establish a link to the imported database table for the created layer(s). This will require a direct `PostGIS`_ connection, which you can set up in the *Connections* section of |short_name| as well (see below).
+| Note that GeoServer should also have read access to that same PostGIS connection.
+
+.. note:: | This method is only available for vector layers.
+ | For raster layers, |short_name| will resort to `file-based storage`_ instead.
-Import into PostGIS database (handled by GeoServer)
+Import into PostGIS database (managed by GeoServer)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-| The layer data is uploaded to tables in a PostGIS database by GeoServer. This method requires the GeoServer Importer extension, which only handles Shapefile imports for vector data.
-| This means that if the data is stored in a GeoPackage originally, attribute names may be renamed due to the 10 character limit of the Shapefile `.dbf` file upon export. Bridge handles this automatically and also makes sure that field names referenced in styles are renamed accordingly.
-| You must select a suitable PostGIS datastore on the GeoServer instance. Selecting this option will trigger a process that lists all the available datastores in each GeoServer workspace (which might take some time):
+The layer data is packaged and uploaded to GeoServer, and a job is scheduled on the server to import the data into a PostGIS database.
-.. image:: ./img/servers_geoserver2.png
+This is a good approach if you do not have direct access to the PostGIS database from your machine, but GeoServer does.
+
+.. note:: | This method is only available for vector layers.
+ | For raster layers, |short_name| will resort to `file-based storage`_ instead.
+Please note that some limitations apply:
+
+1. This method requires the GeoServer `Importer extension `_ to be installed and enabled.
+2. Because Importer can only import vector data from Shapefiles, attribute names may be shortened on export to 10 characters (`.dbf` limitation). Those names will also be applied to the PostGIS table attributes. However, |short_name| will try to make sure that attribute names referenced in styles are renamed accordingly, so the styles won't break.
+3. Created PostGIS tables must be deleted manually. Please read :ref:`this warning ` for more information.
+
+Datastore selection
++++++++++++++++++++
+
+In the *Import into PostGIS database (managed by GeoServer)* mode, you must either:
+
+- select an existing PostGIS datastore connection on GeoServer that can act as a template;
+- or define a new PostGIS connection to use on the GeoServer side.
+
+|short_name| will automatically try to list all available PostGIS datastores on GeoServer.
+You can select any datastore as the template that |short_name| should use to create a new datastore with the same connection details as the selected one.
+
+.. image:: ./img/servers_geoserver2.png
.. note:: | The listed datastores will be prefixed by the workspace name to which they belong.
- | This does **not** mean that the layers will be published to that workspace as well.
- | |short_name| always publishes layers to a (new) workspace named after the QGIS project name
- (see :ref:`HowToPublish`), but it will use the same datastore *connection details* as
- the datastore that you have selected.
+ | This does **not** mean that the layers will be published to that workspace.
+
+Alternatively, you can click the |addbutton| button to create a new datastore yourself, if you know the connection details.
+Note that this is the connection that **GeoServer** should use, and that the connection might not work locally on your machine.
-| If you wish to add a new PostGIS-backed datastore, click the :guilabel:`Add datastore` button.
-| This will open a dialog that allows you to specify the connection details. Make sure that GeoServer has full access to the specified PostGIS instance.
-| For more options (or if you wish to specify a JNDI connection pool) please create the datastore using the GeoServer admin page instead.
+For more fine-grained control, or if you wish to specify a JNDI connection pool instead, please create the datastore in the GeoServer Web UI instead.
+|short_name| should then pick up the new datastore automatically, so you can select that as a template.
+
+.. _ImporterWarning:
.. warning:: | Neither the GeoServer REST API nor the Importer extension is authorized to delete underlying PostGIS layer data tables.
| This means that Bridge also won't be able to clean up these data tables and that each publication will create new tables in the database,
@@ -134,7 +186,6 @@ Setting up this connection is required when using the :ref:`PostGISDirectOption`
.. image:: ./img/servers_postgis.png
-
.. note:: JNDI connection pool support is currently unavailable.