Update documentation

GeoCat · Jul 13, 2023 · 56fbbe1 · 56fbbe1
1 parent ad4a3b3
commit 56fbbe1
Show file tree

Hide file tree

Showing 137 changed files with 8,790 additions and 0 deletions.
diff --git a/index.html b/index.html
@@ -25,6 +25,7 @@ <h1>GeoCat Bridge for QGIS &mdash; community docs</h1>
                 <div class="toctree-wrapper compound">
                     <ul>
                         <li class="toctree-l1"><a href="latest/">latest</a></li>
+                        <li class="toctree-l1"><a href="v4.4/">v4.4</a></li>
                         <li class="toctree-l1"><a href="v4.3/">v4.3</a></li>
                         <li class="toctree-l1"><a href="v4.2/">v4.2</a></li>
                         <li class="toctree-l1"><a href="v4.1/">v4.1</a></li>

diff --git a/v4.4/.buildinfo b/v4.4/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 01ee492b147aabc6ab5ba56da518065f
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/v4.4/.doctrees/background.doctree b/v4.4/.doctrees/background.doctree
diff --git a/v4.4/.doctrees/bridge_dialog.doctree b/v4.4/.doctrees/bridge_dialog.doctree
diff --git a/v4.4/.doctrees/environment.pickle b/v4.4/.doctrees/environment.pickle
diff --git a/v4.4/.doctrees/index.doctree b/v4.4/.doctrees/index.doctree
diff --git a/v4.4/.doctrees/installation.doctree b/v4.4/.doctrees/installation.doctree
diff --git a/v4.4/.doctrees/metadata_editing.doctree b/v4.4/.doctrees/metadata_editing.doctree
diff --git a/v4.4/.doctrees/publish.doctree b/v4.4/.doctrees/publish.doctree
diff --git a/v4.4/.doctrees/quickstart.doctree b/v4.4/.doctrees/quickstart.doctree
diff --git a/v4.4/.doctrees/server_configuration.doctree b/v4.4/.doctrees/server_configuration.doctree
diff --git a/v4.4/.doctrees/styleviewer.doctree b/v4.4/.doctrees/styleviewer.doctree
diff --git a/v4.4/.doctrees/supported_symbology.doctree b/v4.4/.doctrees/supported_symbology.doctree
diff --git a/v4.4/_images/bridgemenuentry.png b/v4.4/_images/bridgemenuentry.png
diff --git a/v4.4/_images/bridgetoolbarbutton.png b/v4.4/_images/bridgetoolbarbutton.png
diff --git a/v4.4/_images/catalog-service-linkage.png b/v4.4/_images/catalog-service-linkage.png
diff --git a/v4.4/_images/categorizedrenderer.png b/v4.4/_images/categorizedrenderer.png
diff --git a/v4.4/_images/fillmarkeroutline.png b/v4.4/_images/fillmarkeroutline.png
diff --git a/v4.4/_images/first_time.png b/v4.4/_images/first_time.png
diff --git a/v4.4/_images/fontmarker.png b/v4.4/_images/fontmarker.png
diff --git a/v4.4/_images/graduatedrenderer.png b/v4.4/_images/graduatedrenderer.png
diff --git a/v4.4/_images/labelbackground.png b/v4.4/_images/labelbackground.png
diff --git a/v4.4/_images/labelhalo.png b/v4.4/_images/labelhalo.png
diff --git a/v4.4/_images/linepatternfill.png b/v4.4/_images/linepatternfill.png
diff --git a/v4.4/_images/loadmetadata.png b/v4.4/_images/loadmetadata.png
diff --git a/v4.4/_images/manually_load_metadata.png b/v4.4/_images/manually_load_metadata.png
diff --git a/v4.4/_images/markerline.png b/v4.4/_images/markerline.png
diff --git a/v4.4/_images/metadata_preview.png b/v4.4/_images/metadata_preview.png
diff --git a/v4.4/_images/metadata_validation.png b/v4.4/_images/metadata_validation.png
diff --git a/v4.4/_images/offline_export.png b/v4.4/_images/offline_export.png
diff --git a/v4.4/_images/pluginmanager.png b/v4.4/_images/pluginmanager.png
diff --git a/v4.4/_images/pluginmanagerbridge.png b/v4.4/_images/pluginmanagerbridge.png
diff --git a/v4.4/_images/pluginmanagermenu.png b/v4.4/_images/pluginmanagermenu.png
diff --git a/v4.4/_images/pointpatternfill.png b/v4.4/_images/pointpatternfill.png
diff --git a/v4.4/_images/preview_gnmetadata.png b/v4.4/_images/preview_gnmetadata.png
diff --git a/v4.4/_images/preview_layers.png b/v4.4/_images/preview_layers.png
diff --git a/v4.4/_images/preview_metadata_button.png b/v4.4/_images/preview_metadata_button.png
diff --git a/v4.4/_images/publish_fields.png b/v4.4/_images/publish_fields.png
diff --git a/v4.4/_images/publish_layers_context_menu.png b/v4.4/_images/publish_layers_context_menu.png
diff --git a/v4.4/_images/publish_layers_list.png b/v4.4/_images/publish_layers_list.png
diff --git a/v4.4/_images/publish_layers_progress.png b/v4.4/_images/publish_layers_progress.png
diff --git a/v4.4/_images/publish_layers_report.png b/v4.4/_images/publish_layers_report.png
diff --git a/v4.4/_images/publish_metadata.png b/v4.4/_images/publish_metadata.png
diff --git a/v4.4/_images/publish_section.png b/v4.4/_images/publish_section.png
diff --git a/v4.4/_images/publish_server_error.png b/v4.4/_images/publish_server_error.png
diff --git a/v4.4/_images/publish_workspace_warning.png b/v4.4/_images/publish_workspace_warning.png
diff --git a/v4.4/_images/quickstart_addauth.png b/v4.4/_images/quickstart_addauth.png
diff --git a/v4.4/_images/quickstart_authentication.png b/v4.4/_images/quickstart_authentication.png
diff --git a/v4.4/_images/quickstart_authset.png b/v4.4/_images/quickstart_authset.png
diff --git a/v4.4/_images/quickstart_geoserverurl.png b/v4.4/_images/quickstart_geoserverurl.png
diff --git a/v4.4/_images/quickstart_newgeoserver.png b/v4.4/_images/quickstart_newgeoserver.png
diff --git a/v4.4/_images/quickstart_newserver.png b/v4.4/_images/quickstart_newserver.png
diff --git a/v4.4/_images/quickstart_olpreview.png b/v4.4/_images/quickstart_olpreview.png
diff --git a/v4.4/_images/quickstart_publishexample.png b/v4.4/_images/quickstart_publishexample.png
diff --git a/v4.4/_images/quickstart_publishprogress.png b/v4.4/_images/quickstart_publishprogress.png
diff --git a/v4.4/_images/quickstart_publishresult.png b/v4.4/_images/quickstart_publishresult.png
diff --git a/v4.4/_images/quickstart_servers.png b/v4.4/_images/quickstart_servers.png
diff --git a/v4.4/_images/quickstart_setdataserver.png b/v4.4/_images/quickstart_setdataserver.png
diff --git a/v4.4/_images/quickstart_titleabstract.png b/v4.4/_images/quickstart_titleabstract.png
diff --git a/v4.4/_images/quickstart_wmspreview.png b/v4.4/_images/quickstart_wmspreview.png
diff --git a/v4.4/_images/rastermarker.png b/v4.4/_images/rastermarker.png
diff --git a/v4.4/_images/remove_all.png b/v4.4/_images/remove_all.png
diff --git a/v4.4/_images/rulebasedrenderer.png b/v4.4/_images/rulebasedrenderer.png
diff --git a/v4.4/_images/servers.png b/v4.4/_images/servers.png
diff --git a/v4.4/_images/servers_geonetwork.png b/v4.4/_images/servers_geonetwork.png
diff --git a/v4.4/_images/servers_geoserver.png b/v4.4/_images/servers_geoserver.png
diff --git a/v4.4/_images/servers_geoserver2.png b/v4.4/_images/servers_geoserver2.png
diff --git a/v4.4/_images/servers_mapserver.png b/v4.4/_images/servers_mapserver.png
diff --git a/v4.4/_images/servers_mapserver2.png b/v4.4/_images/servers_mapserver2.png
diff --git a/v4.4/_images/servers_postgis.png b/v4.4/_images/servers_postgis.png
diff --git a/v4.4/_images/simplefill.png b/v4.4/_images/simplefill.png
diff --git a/v4.4/_images/simpleline.png b/v4.4/_images/simpleline.png
diff --git a/v4.4/_images/simplemarker.png b/v4.4/_images/simplemarker.png
diff --git a/v4.4/_images/singlesymbolrenderer.png b/v4.4/_images/singlesymbolrenderer.png
diff --git a/v4.4/_images/styleviewer.png b/v4.4/_images/styleviewer.png
diff --git a/v4.4/_images/styleviewer_menu.png b/v4.4/_images/styleviewer_menu.png
diff --git a/v4.4/_images/svgmarker.png b/v4.4/_images/svgmarker.png
diff --git a/v4.4/_images/validation.png b/v4.4/_images/validation.png
diff --git a/v4.4/_sources/background.rst.txt b/v4.4/_sources/background.rst.txt
@@ -0,0 +1,61 @@
+Background
+##########
+
+When publishing data to the internet it is common practice to provide
+the data using standardized exchange protocols. Adopting standards
+facilitates a wide usage of the data. Within the geospatial domain, the OGC
+and ISO TC211 data exchange standards are industry standards and
+are often required by law, e.g. the European INSPIRE regulations.
+
+The |app_name| extension takes care of exporting your map, data, styles and metadata to
+opensource mapping platforms that provide data exchange and catalog
+services that comply with these standards. |short_name| will properly link service and metadata
+and vice versa, so users can easily bind to a service from a catalog search result or find the
+relevant metadata for an exposed dataset.
+
+.. image:: ./img/catalog-service-linkage.png
+
+Serverside software components currently supported by |short_name| are GeoServer, MapServer and GeoNetwork.
+Some options are available to migrate data to and expose data from PostGIS.
+
+You can also choose to save the metadata and map symbology on your computer as files
+or in a GeoPackage so you can use them to publish on other software platforms
+(e.g. deegree, QGIS).
+
+Supported server types and formats
+==================================
+
+`GeoServer <http://geoserver.org/>`_ is the reference implementation of
+the Open Geospatial Consortium (OGC)_ Web Feature Service (WFS) and Web
+Coverage Service (WCS) standards, as well as a high performance
+certified compliant Web Map Service (WMS). GeoServer has a REST API,
+which can be used to configure feature types. |short_name| uses this API to publish data.
+Geoserver internally uses `SLD <https://www.opengeospatial.org/standards/sld>`_
+to define the visualisation of data layers.
+
+`MapServer <https://mapserver.org>`_ is an Open Source platform for
+publishing spatial data and interactive mapping applications to the web.
+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|.
+
+`GeoNetwork <https://geonetwork-opensource.org>`_ is a catalog for registering
+assets, such as spatial datasets. It contains a CatalogService 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).
+
+`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.
+
+`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
+to be consumed by data services.
diff --git a/v4.4/_sources/bridge_dialog.rst.txt b/v4.4/_sources/bridge_dialog.rst.txt
@@ -0,0 +1,47 @@
+The |short_name| Dialog
+=======================
+
+Most of the interaction with |app_name| is done through the |short_name| dialog.
+To open it, select the `Publish` button on the `Web toolbar` or look for it under the |menu_name| menu.
+
+.. image:: ./img/bridgemenuentry.png
+
+The first time you open the |short_name| dialog, you will see a landing page with information about
+|short_name| and other |publisher| products. Follow the corresponding links to find out more about these
+products and how they can be used with |short_name|.
+
+.. image:: ./img/first_time.png
+
+
+.. tip::   At the bottom of the `About` panel, it should display the |app_name| version that you are currently running.
+
+
+As you can see, there are 2 more panels besides the `About` panel mentioned above:
+
+- Publish
+- Servers
+
+We will have closer look at these panels on the following pages.
+
+Logging and error handling
+--------------------------
+
+| If you are experiencing unexpected behavior, you should open the |app_name| log message panel to find out if |short_name| has been logging some errors or warnings.
+| 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.
+
+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:
+
+- 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.
diff --git a/v4.4/_sources/index.rst.txt b/v4.4/_sources/index.rst.txt
@@ -0,0 +1,33 @@
+|plugin_name|
+=============
+
+|plugin_name| enables you to publish your map metadata to a spatial catalogue (CSW)
+like GeoNetwork, or to publish the map itself as an OGC data service (WMS/WMTS/WFS/WCS)
+to GeoServer or MapServer. |short_name| also offers the option to export metadata, symbology
+and/or data as local files.
+
+This QGIS plugin has been developed by `GeoCat <https://www.geocat.net>`_,
+a Dutch-Canadian company focusing on the development, customization
+and support of cutting-edge geospatial catalog software on both server and desktop platforms.
+GeoCat provides all-in-one Spatial Data Infrastructure (SDI) solutions
+that offer a geospatial catalog, map server and map client.
+The software is based on established Free and Open Source Software (FOSS4G)
+projects, and uses open standard protocols.
+
+
+Contents
+--------
+
+.. toctree::
+    :glob:
+    :maxdepth: 2
+
+    background
+    installation
+    quickstart
+    bridge_dialog
+    server_configuration
+    publish
+    metadata_editing
+    styleviewer
+    supported_symbology
diff --git a/v4.4/_sources/installation.rst.txt b/v4.4/_sources/installation.rst.txt
@@ -0,0 +1,86 @@
+Installation
+############
+
+Requirements
+************
+
+Client-side
+-----------
+
+|app_name| requires QGIS |min_qgis_ver| or newer.
+Both the standalone QGIS installation or the OSGeo distribution should work.
+
+QGIS users who use a QGIS version *beyond* 3.16 should verify that the ``lxml`` :ref:`Python dependency <lxml-dependency>` is available.
+However, this only applies if you wish to import or publish metadata using |short_name|.
+
+.. note::   If you access the internet through a proxy server,
+            you might experience some issues while publishing data or connecting to a server.
+
+Server-side
+-----------
+
+GeoNetwork
+^^^^^^^^^^
+
+|app_name| currently supports GeoNetwork version 3.4 and up.
+GeoNetwork 2.x support has been deprecated. Version 4.x is supported, but experimental.
+
+GeoServer
+^^^^^^^^^
+
+-   Support starts at GeoServer version 2.13 and up. However, other
+    versions since 2.4 are expected to run fine in most of the
+    cases.
+-   If you wish to use a direct connection to PostGIS (i.e. let |short_name|
+    handle the data upload instead of the GeoServer REST API), you will
+    need to have access to that database instance.
+-   If you wish to let GeoServer import your data into PostGIS (i.e. through
+    the REST API instead of direct access), you need to make sure that the
+    `Importer extension <https://docs.geoserver.org/latest/en/user/extensions/importer/index.html>`_
+    is available on GeoServer.
+    If you do not know if this extension is installed, simply try to publish
+    something and |short_name| will warn you if it isn't.
+
+MapServer
+^^^^^^^^^
+
+-   MapServer support starts at version 6.2 and up.
+    However, other versions since 5.6 are expected to run fine in most of the cases.
+-   FTP connection or file write access to MapServer project path.
+
+.. _installing-bridge:
+
+How to install
+**************
+
+To install the |plugin_name|, please follow these steps:
+
+1. Open the :guilabel:`QGIS Plugin Manager` by clicking on the :menuselection:`Plugins --> Manage and Install Plugins...` menu entry.
+
+    .. image:: ./img/pluginmanagermenu.png
+
+    You will now see a dialog similar to the one below, listing all your (pre-)installed plugins:
+
+    .. image:: ./img/pluginmanager.png
+
+2. Click the :guilabel:`All` section on the sidebar to list all available plugins. Scroll down to find "|app_name|"
+or use the search box at the top to filter the list (e.g. by typing "|short_name|"). Clicking on the "|app_name|" plugin entry
+will display detailed information about the plugin:
+
+    .. image:: ./img/pluginmanagerbridge.png
+
+
+3. Click :guilabel:`Install Plugin` and wait until |short_name| has been downloaded and installed.
+
+4. Close the Plugin Manager when done. You should now have a new menu entry under the :menuselection:`Web` menu,
+which contains a couple of menu items related to the |short_name| plugin:
+
+    .. image:: ./img/bridgemenuentry.png
+
+5. You should also see a new toolbar button, that will open the |short_name| Publish dialog.
+
+    .. image:: ./img/bridgetoolbarbutton.png
+
+
+In the Plugin Manager settings, note that you can configure QGIS to automatically check for plugin updates.
+Alternatively, you can update plugins manually using the :guilabel:`Upgrade All` button.
diff --git a/v4.4/_sources/metadata_editing.rst.txt b/v4.4/_sources/metadata_editing.rst.txt
@@ -0,0 +1,80 @@
+.. _MetadataEditing:
+
+Metadata Editing
+================
+
+|app_name| provides a basic editor for metadata properties to create
+ISO19139-compliant metadata records. The purpose of this editor is to easily
+complete a minimal subset of required metadata elements:
+
+-   Title
+-   Abstract
+-   ISO topic category
+-   Keywords
+-   Metadata contact
+-   Data contact
+-   Access constraints (used for data license)
+-   Use constraints (also known as Fees)
+-   Metadata language
+
+When publishing metadata to GeoNetwork, |short_name| will convert the QGIS metadata (QMD) into the ISO19139 format.
+Note that in order to do that, |short_name| uses the ``lxml`` library, which :ref:`may not be installed <lxml-dependency>`.
+
+| You can edit the |short_name| metadata fields directly, or use the QGIS metadata editor by clicking the :guilabel:`Open QGIS metadata editor` button.
+| Note that you can also click the :guilabel:`...` buttons next to each |short_name| metadata field to open the QGIS metadata editor a specific page:
+
+.. image:: ./img/publish_metadata.png
+
+
+Preview metadata
+----------------
+
+To see a preview of the metadata of the selected layer, click the |previewmetadata| button.
+
+.. |previewmetadata| image:: ./img/preview_metadata_button.png
+
+This will open a new dialog and render the metadata as a simple HTML webpage:
+
+.. image:: ./img/metadata_preview.png
+
+
+Metadata validation
+-------------------
+
+|short_name| can use built-in QGIS validation tools and display the result of the metadata validation.
+Click the |validatemetadata| button to validate your metadata.
+
+.. |validatemetadata| image:: ./img/validation.png 
+
+After validation a dialog with the results is displayed:
+
+.. image:: ./img/metadata_validation.png
+
+Load metadata
+-------------
+
+If your layer has metadata in ISO19139 or ESRI-ISO (ISO19115 or FGDC) format, and that metadata is available in an auxiliary file stored alongside the data file, QGIS will *not* automatically read it.
+
+| QGIS only has native support for its own `qmd` format. However, |short_name| is able to import the metadata.
+| Select the layer in the |short_name| dialog and click the |loadmetadata| button.
+
+.. |loadmetadata| image:: ./img/loadmetadata.png 
+
+| |short_name| will look in the folder where the layer file is stored and try to find a metadata file named either `[layer_filename].[extension].xml` or `[layer_filename].xml`.
+| For example, for a layer data source named `countries.shp`, it will search for both `countries.shp.xml` and `countries.xml`.
+  If such a file exists, and it is in one of the supported ISO formats mentioned above, |short_name| will convert it into the QGIS metadata format and import all elements that it could find.
+| If no auxiliary metadata file could be found, |short_name| will ask you if you wish to manually select it:
+
+.. image:: ./img/manually_load_metadata.png
+
+If you click :guilabel:`Yes`, a file dialog will open so you can select the metadata file to import.
+
+.. note::   - Some (non-supported) elements of the original metadata may get lost in the transformation.
+            - Changes in the metadata editor will not be saved to the original imported metadata file.
+            - Because of a :ref:`dependency <lxml-dependency>`, |short_name| may not be able to import metadata.
+              If this is the case, a warning will be displayed.
+
+.. warning::    | **If you wish to persist the imported/edited metadata for another time, it is important that you
+                  save the QGIS project before your close the application.**
+                | However, within the same QGIS session (i.e. for the time that the application is being used),
+                  the metadata for each layer will be memorized.