Update documentation

GeoCat · Oct 5, 2024 · 466f6bc · 466f6bc
1 parent bb1e257
commit 466f6bc
Show file tree

Hide file tree

Showing 32 changed files with 141 additions and 45 deletions.
diff --git 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 <https://www.mapserver.org/mapfile/>`_,
-which can be generated by |short_name|.
+which can be generated by |short_name|, but support for it is limited.
 
 `GeoNetwork <https://geonetwork-opensource.org>`_ 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 <https://geostyler.org/>`_ is a JS library used in the `Shogun framework <https://github.com/terrestris/shogun-core>`_
-to create generic styles. GeoServer also has a `plugin <https://docs.geoserver.org/latest/en/user/community/geostyler/index.html>`_
-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 <https://geostyler.org/>`_ is a NodeJS tool by Terrestris to create map styles.
+GeoServer also has a `plugin <https://docs.geoserver.org/latest/en/user/community/geostyler/index.html>`_
+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 <https://github.com/GeoCat/bridge-style>`_ library, that utilizes
+GeoStyler JSON as an intermediate format before it converts it to various other formats (SLD, Mapfile, etc.).
 
 `Mapbox Style <https://docs.mapbox.com/mapbox-gl-js/style-spec/>`_ is a style format that defines the visual
 appearance of vector tiles in the `Mapbox JavaScript API <https://docs.mapbox.com/mapbox-gl-js/api/>`_.
-|short_name| is able to generate a Mapbox style document.
+|short_name| is able to generate a Mapbox or `MapLibre <https://maplibre.org/>`_ style document, but newer versions
+of both specifications may not be fully compatible anymore.
 
 `PostGIS <https://postgis.net/>`_ 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
@@ -25,18 +25,21 @@ 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)
 - Spanish (Español)
 
 | 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 <https://explore.transifex.com/geocat/bridge-common>`_.
diff --git 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
diff --git a/docs/source/img/favicon.ico b/docs/source/img/favicon.ico
diff --git a/docs/source/img/loadmetadata.png b/docs/source/img/loadmetadata.png
diff --git a/docs/source/img/manually_load_metadata.png b/docs/source/img/manually_load_metadata.png
diff --git a/docs/source/img/preview_metadata_button.png b/docs/source/img/preview_metadata_button.png
diff --git a/docs/source/img/publish_layers_context_menu.png b/docs/source/img/publish_layers_context_menu.png
diff --git a/docs/source/img/publish_layers_list.png b/docs/source/img/publish_layers_list.png
diff --git a/docs/source/img/publish_layers_progress.png b/docs/source/img/publish_layers_progress.png
diff --git a/docs/source/img/publish_layers_report.png b/docs/source/img/publish_layers_report.png
diff --git a/docs/source/img/publish_section.png b/docs/source/img/publish_section.png
diff --git a/docs/source/img/publish_workspace_warning.png b/docs/source/img/publish_workspace_warning.png
diff --git a/docs/source/img/quickstart_authentication.png b/docs/source/img/quickstart_authentication.png
diff --git a/docs/source/img/quickstart_newgeoserver.png b/docs/source/img/quickstart_newgeoserver.png
diff --git a/docs/source/img/quickstart_publishexample.png b/docs/source/img/quickstart_publishexample.png
diff --git a/docs/source/img/quickstart_publishprogress.png b/docs/source/img/quickstart_publishprogress.png
diff --git a/docs/source/img/quickstart_publishresult.png b/docs/source/img/quickstart_publishresult.png
diff --git a/docs/source/img/quickstart_titleabstract.png b/docs/source/img/quickstart_titleabstract.png
diff --git a/docs/source/img/quickstart_wmspreview.png b/docs/source/img/quickstart_wmspreview.png
diff --git a/docs/source/img/servers.png b/docs/source/img/servers.png
diff --git a/docs/source/img/servers_geonetwork.png b/docs/source/img/servers_geonetwork.png
diff --git a/docs/source/img/servers_geoserver.png b/docs/source/img/servers_geoserver.png
diff --git a/docs/source/img/servers_geoserver2.png b/docs/source/img/servers_geoserver2.png
diff --git a/docs/source/img/servers_mapserver.png b/docs/source/img/servers_mapserver.png
diff --git a/docs/source/img/servers_mapserver2.png b/docs/source/img/servers_mapserver2.png
diff --git a/docs/source/img/servers_postgis.png b/docs/source/img/servers_postgis.png
diff --git a/docs/source/img/validation.png b/docs/source/img/validation.png
diff --git 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
@@ -1,6 +1,8 @@
 Quickstart Tutorial
 ###################
 
+    .. |nbsp| unicode:: 0xA0
+
 Once |app_name| has been :ref:`installed <installing-bridge>`, 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: