Complete initial reference documentation (maplibre#152)

* Add widgets documentation

* Add basic location / QML documentation

* Specify header files

* Install doxyqml in the CI

* Minor tweaks to the added QML files

.github/workflows/docs-test.yml

@@ -33,6 +33,9 @@ jobs:
         with:
           version: "1.10.0"
 
+      - name: Install doxyqml
+        run: pip install doxyqml
+
       - name: Generate documentation
         working-directory: docs
         run: doxygen

.github/workflows/gh-pages-docs.yml

@@ -18,6 +18,9 @@ jobs:
         with:
           version: "1.10.0"
 
+      - name: Install doxyqml
+        run: pip install doxyqml
+
       - name: Generate documentation
         working-directory: docs
         run: doxygen

.gitignore

@@ -2,3 +2,4 @@
 *.user
 compile_commands.json
 docs/output
+.venv

docs/Doxyfile

@@ -348,7 +348,7 @@ OPTIMIZE_OUTPUT_SLICE  = NO
 #
 # Note see also the list of default file extension mappings.
 
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = qml=C++
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -783,7 +783,7 @@ MAX_INITIALIZER_LINES  = 30
 # list will mention the files that were used to generate the documentation.
 # The default value is: YES.
 
-SHOW_USED_FILES        = YES
+SHOW_USED_FILES        = NO
 
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
 # will remove the Files entry from the Quick Index and from the Folder Tree View
@@ -951,6 +951,8 @@ WARN_LOGFILE           =
 
 INPUT                  = \
   ../src/core \
+  ../src/widgets \
+  location \
   Documentation.md \
   Building.md \
   Usage.md
@@ -1043,7 +1045,8 @@ FILE_PATTERNS          = *.c \
                          *.vhdl \
                          *.ucf \
                          *.qsf \
-                         *.ice
+                         *.ice \
+                         *.qml
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -1074,7 +1077,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = *_p.hpp
+EXCLUDE_PATTERNS       = *_p.hpp example_* snippets_*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1088,7 +1091,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1147,7 +1150,7 @@ INPUT_FILTER           =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by doxygen.
 
-FILTER_PATTERNS        =
+FILTER_PATTERNS        = *.qml=doxyqml
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 # INPUT_FILTER) will also be used to filter the input files that are used for

docs/README.md

@@ -7,12 +7,15 @@ of MapLibre Native Qt Bindings using [Doxygen](https://www.doxygen.nl).
 is used as a theme and is included as a submodule.
 To update, simply check out a new version of the submodule.
 
-The `[Documentation.md](./Documentation.md)` file contains the contents of
+The [`Documentation.md`](./Documentation.md) file contains the contents of
 the first page you see when you open the documentation website,
-while `[config/header.html](./config/header.html)` and
-`[config/footer.html](./config/footer.html)`contain the contents of
+while [`config/header.html`](./config/header.html) and
+[`config/footer.html`](./config/footer.html) contain the contents of
 the header and the footer, respectively.
 
+Standalone documentation is available at [`location`](./location/) with
+examples provided in the [`examples`](./examples/) directory.
+
 To generate the documentation, run
 
 ```shell

docs/examples/example_Style.qml

@@ -0,0 +1,57 @@
+import QtQuick 2.15
+import QtLocation 6.5
+import QtPositioning 6.5
+
+import MapLibre 3.0
+
+Item {
+    width: 512
+    height: 512
+
+    Plugin {
+        id: mapPlugin
+        name: "maplibre"
+
+        PluginParameter {
+            name: "maplibre.map.styles"
+            value: "https://demotiles.maplibre.org/style.json"
+        }
+    }
+
+    MapView {
+        id: mapView
+        anchors.fill: parent
+        map.plugin: mapPlugin
+
+        map.zoomLevel: 5
+        map.center: QtPositioning.coordinate(41.874, -75.789)
+
+        MapLibre.style: Style {
+            id: style
+
+            SourceParameter {
+                id: radarSourceParam
+                styleId: "radar"
+                type: "image"
+                property string url: "https://maplibre.org/maplibre-gl-js/docs/assets/radar1.gif"
+                property var coordinates: [
+                    [-80.425, 46.437],
+                    [-71.516, 46.437],
+                    [-71.516, 37.936],
+                    [-80.425, 37.936]
+                ]
+            }
+
+            LayerParameter {
+                id: radarLayerParam
+                styleId: "radar-layer"
+                type: "raster"
+                property string source: "radar"
+
+                paint: {
+                    "raster-opacity": 0.9
+                }
+            }
+        }
+    }
+}

docs/examples/snippets_Map.qml

@@ -0,0 +1,26 @@
+//! [Map plugin]
+Plugin {
+    id: mapPlugin
+    name: "maplibre"
+
+    PluginParameter {
+        name: "maplibre.map.styles"
+        value: "https://demotiles.maplibre.org/style.json"
+    }
+}
+//! [Map plugin]
+
+//! [Style attachment]
+MapView {
+    id: mapView
+    anchors.fill: parent
+    map.plugin: mapPlugin
+
+    map.zoomLevel: 5
+    map.center: QtPositioning.coordinate(41.874, -75.789)
+
+    MapLibre.style: Style {
+        id: style
+    }
+}
+//! [Style attachment]

docs/examples/snippets_Style.qml

@@ -0,0 +1,72 @@
+//! [Attaching a Style]
+MapLibre.style: Style {
+    id: style
+
+    SourceParameter {
+        id: radarSourceParam
+        styleId: "radar"
+        type: "image"
+        property string url: "https://maplibre.org/maplibre-gl-js/docs/assets/radar1.gif"
+        property var coordinates: [
+            [-80.425, 46.437],
+            [-71.516, 46.437],
+            [-71.516, 37.936],
+            [-80.425, 37.936]
+        ]
+    }
+
+    LayerParameter {
+        id: radarLayerParam
+        styleId: "radar-layer"
+        type: "raster"
+        property string source: "radar"
+
+        paint: {
+            "raster-opacity": 0.9
+        }
+    }
+}
+//! [Attaching a Style]
+
+//! [Adding a parameter to a style]
+let layerParam = Qt.createQmlObject(`
+    import MapLibre 3.0
+
+    LayerParameter {
+        styleId: "tileLayer"
+        type: "raster"
+        property string source: "tileSource"
+    }
+    `,
+    style,
+    "layerParamSnippet")
+style.addParameter(layerParam)
+//! [Adding a parameter to a style]
+
+//! [Source parameter]
+SourceParameter {
+    id: radarSourceParam
+    styleId: "radar"
+    type: "image"
+    property string url: "https://maplibre.org/maplibre-gl-js/docs/assets/radar1.gif"
+    property var coordinates: [
+        [-80.425, 46.437],
+        [-71.516, 46.437],
+        [-71.516, 37.936],
+        [-80.425, 37.936]
+    ]
+}
+//! [Source parameter]
+
+//! [Layer parameter]
+LayerParameter {
+    id: radarLayerParam
+    styleId: "radar-layer"
+    type: "raster"
+    property string source: "radar"
+
+    paint: {
+        "raster-opacity": 0.9
+    }
+}
+//! [Layer parameter]

docs/location/LayerParameter.qml

@@ -0,0 +1,20 @@
+// Copyright (C) 2024 MapLibre contributors
+
+// SPDX-License-Identifier: BSD-2-Clause
+
+/*!
+    \class LayerParameter
+    \brief A QML type for setting parameters of a layer. Generated from \ref QMapLibre::LayerParameter and should be nested in a \ref Style.
+    \ingroup QMapLibreLocation
+
+    Additional layer-specific properties can be set directly as QML properties
+    to the instance of the LayerParameter.
+
+    \snippet{trimleft} snippets_Style.qml Layer parameter
+*/
+
+SourceParameter {
+    property string type //!< layer type
+    property object layout //!< layout properties as a dictionary
+    property object paint //!< paint properties as a dictionary
+}

docs/location/QMapLibreLocation.dox

@@ -0,0 +1,14 @@
+/*!
+    \defgroup QMapLibreLocation QMapLibre Location
+    \brief Qt Location plugin for MapLibre with the ID \c maplibre.
+
+    The Qt Location QML plugin can be set with the \c Plugin instance.
+
+    \snippet{trimleft} snippets_Map.qml Map plugin
+
+    Additional style properties can be attached to the map.
+    For that <tt>import MapLibre 3.0</tt> is needed.
+    See \ref Style for more details.
+
+    \snippet{trimleft} snippets_Map.qml Style attachment
+*/

docs/location/SourceParameter.qml

@@ -0,0 +1,18 @@
+// Copyright (C) 2024 MapLibre contributors
+
+// SPDX-License-Identifier: BSD-2-Clause
+
+/*!
+    \class SourceParameter
+    \brief A QML type for setting parameters of a source. Generated from \ref QMapLibre::SourceParameter and should be nested in a \ref Style.
+    \ingroup QMapLibreLocation
+
+    Additional source-specific properties can be set directly as QML properties
+    to the instance of the SourceParameter.
+
+    \snippet{trimleft} snippets_Style.qml Source parameter
+*/
+
+Item {
+    property string m_type //!< source type
+}

docs/location/Style.qml

@@ -0,0 +1,41 @@
+// Copyright (C) 2024 MapLibre contributors
+
+// SPDX-License-Identifier: BSD-2-Clause
+
+/*!
+    \class Style
+    \brief A QML helper item to be attached to a \c MapView using \c MapLibre.style property.
+    \ingroup QMapLibreLocation
+
+    This item does not have any properties and expect to have \ref StyleParameter
+    implementations as children. See also \ref SourceParameter and \ref LayerParameter.
+
+    \snippet{trimleft} snippets_Style.qml Attaching a Style
+
+    Parameters can also be manipulated programatically using \ref addParameter,
+    \ref removeParameter and \ref clearParameters functions.
+
+    \snippet{trimleft} snippets_Style.qml Adding a parameter to a style
+
+    \example example_Style.qml
+    This is an example of how to use the Style item.
+*/
+
+Item {
+    /*!
+        \brief Add a parameter programatically
+        \param type:StyleParameter parameter The parameter to be added
+    */
+    function addParameter(parameter) {}
+
+    /*!
+        \brief Remove a parameter programatically
+        \param type:StyleParameter parameter The parameter to be removed
+    */
+    function removeParameter(parameter) {}
+
+    /*!
+        \brief Clear all parameters programatically
+    */
+    function clearParameters() {}
+}

docs/location/StyleParameter.qml

@@ -0,0 +1,15 @@
+// Copyright (C) 2024 MapLibre contributors
+
+// SPDX-License-Identifier: BSD-2-Clause
+
+/*!
+    \class StyleParameter
+    \brief A base QML type for style parameters and is not intended to be used directly.
+    \ingroup QMapLibreLocation
+
+    See also \ref SourceParameter and \ref LayerParameter.
+*/
+
+Item {
+    property string styleId //!< style id to be references inside MapLibre
+}

src/core/map.cpp

@@ -253,6 +253,8 @@ namespace QMapLibre {
     \brief The Map class is a Qt wrapper for the MapLibre Native engine.
     \ingroup QMapLibre
 
+    \headerfile map.hpp <QMapLibre/Map>
+
     Map is a Qt friendly version the MapLibre Native engine using Qt types
     and deep integration with Qt event loop. Map relies as much as possible
     on Qt, trying to minimize the external dependencies. For instance it will

src/core/settings.cpp

@@ -64,6 +64,8 @@ namespace QMapLibre {
     \brief The Settings class stores the initial configuration for Map.
     \ingroup QMapLibre
 
+    \headerfile settings.hpp <QMapLibre/Settings>
+
     Settings is used to configure Map at the moment of its creation.
     Once created, the Settings of a Map can no longer be changed.