Some fixes to numbered list handling in dox/PyQGIS API

qgis · Jun 15, 2020 · 74400c7 · 74400c7
1 parent 1ef12a0
commit 74400c7
Show file tree

Hide file tree

Showing 25 changed files with 148 additions and 147 deletions.
diff --git a/python/core/auto_generated/geometry/qgsgeometry.sip.in b/python/core/auto_generated/geometry/qgsgeometry.sip.in
@@ -601,12 +601,12 @@ Returns the indexes of the vertices before and after the given vertex index.
 
 This function takes into account the following factors:
 
-1. If the given vertex index is at the end of a linestring,
-the adjacent index will be -1 (for "no adjacent vertex")
-2. If the given vertex index is at the end of a linear ring
-(such as in a polygon), the adjacent index will take into
-account the first vertex is equal to the last vertex (and will
-skip equal vertex positions).
+# If the given vertex index is at the end of a linestring,
+  the adjacent index will be -1 (for "no adjacent vertex")
+# If the given vertex index is at the end of a linear ring
+  (such as in a polygon), the adjacent index will take into
+  account the first vertex is equal to the last vertex (and will
+  skip equal vertex positions).
 %End
 
     bool insertVertex( double x, double y, int beforeVertex );

diff --git a/python/core/auto_generated/qgscoordinatereferencesystem.sip.in b/python/core/auto_generated/qgscoordinatereferencesystem.sip.in
@@ -29,12 +29,11 @@ allows lookups of CRS and seamless conversions between the various definitions.
 
 Most commonly one comes across two types of coordinate systems:
 
-1. **Geographic coordinate systems** - based on a geodetic datum, normally with coordinates being
-latitude/longitude in degrees. The most common one is World Geodetic System 84 (WGS84).
-
-2. **Projected coordinate systems** - based on a geodetic datum with coordinates projected to a plane,
-typically using meters or feet as units. Common projected coordinate systems are Universal
-Transverse Mercator or Albers Equal Area.
+# Geographic coordinate systems: based on a geodetic datum, normally with coordinates being
+  latitude/longitude in degrees. The most common one is World Geodetic System 84 (WGS84).
+# Projected coordinate systems: based on a geodetic datum with coordinates projected to a plane,
+  typically using meters or feet as units. Common projected coordinate systems are Universal
+  Transverse Mercator or Albers Equal Area.
 
 Internally QGIS uses proj library for all the math behind coordinate transformations, so in case
 of any troubles with projections it is best to examine the PROJ representation within the object,
@@ -68,10 +67,10 @@ CRS Definition Formats
 
 This section gives an overview of various supported CRS definition formats:
 
-1. **Authority and Code.** Also referred to as OGC WMS format within QGIS as they have been widely
-used in OGC standards. These are encoded as `<auth>:<code>`, for example `EPSG:4326` refers
-to WGS84 system. EPSG is the most commonly used authority that covers a wide range
-of coordinate systems around the world.
+# Authority and Code: Also referred to as OGC WMS format within QGIS as they have been widely
+  used in OGC standards. These are encoded as `<auth>:<code>`, for example `EPSG:4326` refers
+  to WGS84 system. EPSG is the most commonly used authority that covers a wide range
+  of coordinate systems around the world.
 
 An extended variant of this format is OGC URN. Syntax of URN for CRS definition is
 `urn:ogc:def:crs:<auth>:[<version>]:<code>`. This class can also parse URNs (versions
@@ -85,23 +84,21 @@ on different machines or user profiles.
 .. seealso:: :py:func:`authid`
 
 .. seealso:: :py:func:`createFromOgcWmsCrs`
-
-2. **PROJ string.** This is a string consisting of a series of key/value pairs in the following
-format: `+param1=value1 +param2=value2 [...]`. This is the format natively used by the
-underlying proj library. For example, the definition of WGS84 looks like this:
+# PROJ string: This is a string consisting of a series of key/value pairs in the following
+  format: `+param1=value1 +param2=value2 [...]`. This is the format natively used by the
+  underlying proj library. For example, the definition of WGS84 looks like this:
 
 .. code-block::
 
-        +proj=longlat +datum=WGS84 +no_defs
+       +proj=longlat +datum=WGS84 +no_defs
 
 
 
 .. seealso:: :py:func:`toProj`
 
 .. seealso:: :py:func:`createFromProj`
-
-3. **Well-known text (WKT).** Defined by Open Geospatial Consortium (OGC), this is another common
-format to define CRS. For WGS84 the OGC WKT definition is the following:
+# Well-known text (WKT): Defined by Open Geospatial Consortium (OGC), this is another common
+  format to define CRS. For WGS84 the OGC WKT definition is the following:
 
 GEOGCS["WGS 84",
 DATUM["WGS_1984",

diff --git a/python/core/auto_generated/qgsdataitemprovider.sip.in b/python/core/auto_generated/qgsdataitemprovider.sip.in
@@ -19,10 +19,11 @@ This is the interface for those who want to add custom data items to the browser
 
 The method :py:func:`~createDataItem` is ever called only if :py:func:`~capabilities` return non-zero value.
 There are two occasions when :py:func:`~createDataItem` is called:
-1. to create root items (passed path is empty, parent item is ``None``).
-2. to create items in directory structure. For this capabilities have to return at least
-of the following: QgsDataProvider.Dir or QgsDataProvider.File. Passed path is the file
-or directory being inspected, parent item is a valid QgsDirectoryItem
+
+# to create root items (passed path is empty, parent item is ``None``).
+# to create items in directory structure. For this capabilities have to return at least
+  of the following: QgsDataProvider.Dir or QgsDataProvider.File. Passed path is the file
+  or directory being inspected, parent item is a valid QgsDirectoryItem
 
 .. versionadded:: 2.10
 %End

diff --git a/python/core/auto_generated/qgsmaplayerrenderer.sip.in b/python/core/auto_generated/qgsmaplayerrenderer.sip.in
@@ -24,13 +24,14 @@ the overhead of copying (both memory and CPU) will be kept low.
 Qt containers and various Qt classes use implicit sharing.
 
 The scenario will be:
-1. renderer job (doing preparation in the GUI thread) calls
-:py:func:`QgsMapLayer.createMapRenderer()` and gets instance of this class.
-The instance is initialized at that point and should not need
-additional calls to QgsVectorLayer.
-2. renderer job (still in GUI thread) stores the renderer for later use.
-3. renderer job (in worker thread) calls :py:func:`QgsMapLayerRenderer.render()`
-4. renderer job (again in GUI thread) will check :py:func:`~errors` and report them
+
+# renderer job (doing preparation in the GUI thread) calls
+  :py:func:`QgsMapLayer.createMapRenderer()` and gets instance of this class.
+  The instance is initialized at that point and should not need
+  additional calls to QgsVectorLayer.
+# renderer job (still in GUI thread) stores the renderer for later use.
+# renderer job (in worker thread) calls :py:func:`QgsMapLayerRenderer.render()`
+# renderer job (again in GUI thread) will check :py:func:`~errors` and report them
 
 .. versionadded:: 2.4
 %End

diff --git a/python/core/auto_generated/qgsmaprendererjob.sip.in b/python/core/auto_generated/qgsmaprendererjob.sip.in
@@ -25,11 +25,11 @@ amount of time.
 
 Common use case:
 
-0. prepare QgsMapSettings with rendering configuration (extent, layer, map size, ...)
-1. create QgsMapRendererJob subclass with QgsMapSettings instance
-2. connect to job's :py:func:`~finished` signal
-3. call :py:func:`~start`. Map rendering will start in background, the function immediately returns
-4. at some point, slot connected to :py:func:`~finished` signal is called, map rendering is done
+# prepare QgsMapSettings with rendering configuration (extent, layer, map size, ...)
+# create QgsMapRendererJob subclass with QgsMapSettings instance
+# connect to job's :py:func:`~finished` signal
+# call :py:func:`~start`. Map rendering will start in background, the function immediately returns
+# at some point, slot connected to :py:func:`~finished` signal is called, map rendering is done
 
 It is possible to cancel the rendering job while it is active by calling :py:func:`~cancel` function.
 

diff --git a/python/core/auto_generated/qgsvectorlayerexporter.sip.in b/python/core/auto_generated/qgsvectorlayerexporter.sip.in
@@ -17,10 +17,9 @@ A convenience class for exporting vector layers to a destination data provider.
 
 QgsVectorLayerExporter can be used in two ways:
 
-1. Using a static call to QgsVectorLayerExporter.exportLayer(...) which exports the
-entire layer to the destination provider.
-
-2. Create an instance of the class and issue calls to addFeature(...)
+# Using a static call to QgsVectorLayerExporter.exportLayer(...) which exports the
+  entire layer to the destination provider.
+# Create an instance of the class and issue calls to addFeature(...)
 
 .. versionadded:: 3.0
 %End

diff --git a/python/core/auto_generated/vectortile/qgsvectortilebasicrenderer.sip.in b/python/core/auto_generated/vectortile/qgsvectortilebasicrenderer.sip.in
@@ -15,9 +15,10 @@ class QgsVectorTileBasicRendererStyle
 {
 %Docstring
 Definition of map rendering of a subset of vector tile data. The subset of data is defined by:
-1. sub-layer name
-2. geometry type (a single sub-layer may have multiple geometry types)
-3. filter expression
+
+# sub-layer name
+# geometry type (a single sub-layer may have multiple geometry types)
+# filter expression
 
 Renering is determined by the associated symbol (QgsSymbol). Symbol has to be of the same
 type as the chosen :py:func:`~geometryType` - i.e. QgsMarkerSymbol for points, QgsLineSymbol for linestrings

diff --git a/python/core/auto_generated/vectortile/qgsvectortilerenderer.sip.in b/python/core/auto_generated/vectortile/qgsvectortilerenderer.sip.in
@@ -70,9 +70,10 @@ class QgsVectorTileRenderer
 Abstract base class for all vector tile renderer implementations.
 
 For rendering it is expected that client code calls:
-1. :py:func:`~QgsVectorTileRendererData.startRender` to prepare renderer
-2. :py:func:`~QgsVectorTileRendererData.renderTile` for each tile
-3. :py:func:`~QgsVectorTileRendererData.stopRender` to clean up renderer and free resources
+
+# :py:func:`~QgsVectorTileRendererData.startRender` to prepare renderer
+# :py:func:`~QgsVectorTileRendererData.renderTile` for each tile
+# :py:func:`~QgsVectorTileRendererData.stopRender` to clean up renderer and free resources
 
 .. versionadded:: 3.14
 %End

diff --git a/python/gui/auto_generated/qgscustomdrophandler.sip.in b/python/gui/auto_generated/qgscustomdrophandler.sip.in
@@ -16,22 +16,20 @@ Abstract base class that may be implemented to handle new types of data to be dr
 
 Implementations have three approaches they can use to handle drops.
 
-1. The simplest approach is to implement :py:func:`~handeFileDrop` when they need to handle
-dropped files (i.e. with mime type "text/uri-list").
-
-2. Reimplement :py:func:`~handleCustomUriDrop` when they want to handle dropped custom
-QgsMimeDataUtils.Uri entries, for instance handling dropping custom entries
-from the browser tree (with mime type "application/x-vnd.qgis.qgis.uri"). In
-this case the implementation's :py:func:`~customUriProviderKey` must match the uri
-entry's providerKey.
-
-3. Reimplement :py:func:`~handleMimeData` to directly handle dropped QMimeData.
-Subclasses should take care when overriding this method. When a drop event
-occurs, Qt will lock the source application of the drag for the duration
-of the drop event handling via :py:func:`~handleMimeData` (e.g. dragging files from
-explorer to QGIS will lock the explorer window until the drop handling has
-been complete). Accordingly :py:func:`~handleMimeData` implementations must return
-quickly and defer any intensive or slow processing.
+# The simplest approach is to implement :py:func:`~handeFileDrop` when they need to handle
+  dropped files (i.e. with mime type "text/uri-list").
+# Reimplement :py:func:`~handleCustomUriDrop` when they want to handle dropped custom
+  QgsMimeDataUtils.Uri entries, for instance handling dropping custom entries
+  from the browser tree (with mime type "application/x-vnd.qgis.qgis.uri"). In
+  this case the implementation's :py:func:`~customUriProviderKey` must match the uri
+  entry's providerKey.
+# Reimplement :py:func:`~handleMimeData` to directly handle dropped QMimeData.
+  Subclasses should take care when overriding this method. When a drop event
+  occurs, Qt will lock the source application of the drag for the duration
+  of the drop event handling via :py:func:`~handleMimeData` (e.g. dragging files from
+  explorer to QGIS will lock the explorer window until the drop handling has
+  been complete). Accordingly :py:func:`~handleMimeData` implementations must return
+  quickly and defer any intensive or slow processing.
 
 .. versionadded:: 3.0
 %End

diff --git a/python/gui/auto_generated/qgsoptionsdialogbase.sip.in b/python/gui/auto_generated/qgsoptionsdialogbase.sip.in
@@ -23,13 +23,14 @@ switching vertical tabs between icon/text to icon-only modes (splitter collapsed
 and connecting QDialogButtonBox's accepted/rejected signals to dialog's accept/reject slots
 
 To use:
-1) Start with copy of qgsoptionsdialog_template.ui and build options/properties dialog.
-2) In source file for dialog, inherit this class instead of QDialog, then in constructor:
-...
-setupUi( this ); // set up .ui file objects
-initOptionsBase( ``False`` ); // set up this class to use .ui objects, optionally restoring base ui
-...
-:py:func:`~restoreOptionsBaseUi`; // restore the base ui with initOptionsBase or use this later on
+
+# Start with copy of qgsoptionsdialog_template.ui and build options/properties dialog.
+# In source file for dialog, inherit this class instead of QDialog, then in constructor:
+  ...
+  setupUi( this ); // set up .ui file objects
+  initOptionsBase( ``False`` ); // set up this class to use .ui objects, optionally restoring base ui
+  ...
+  :py:func:`~restoreOptionsBaseUi`; // restore the base ui with initOptionsBase or use this later on
 %End
 
 %TypeHeaderCode

diff --git a/scripts/sipify.pl b/scripts/sipify.pl
@@ -192,18 +192,14 @@ sub processDoxygenLine {
     if ( $line =~ m/^##\s+(.*)$/) {
       $line = "$1\n".('=' x length($1));
     }
-    if ( $line =~ m/^#\s+(.*)$/) {
-      $line = "$1\n".('*' x length($1));
-    }
-
 
     if ( $line eq '*' ) {
         $line = '';
     }
 
     # handle multi-line parameters/returns/lists
     if ($line ne '') {
-        if ( $line =~ m/^\s*\-/ ){
+        if ( $line =~ m/^\s*[\-#]/ ){
             # start of a list item, ensure following lines are correctly indented
             $line = "$PREV_INDENT$line";
             $INDENT = $PREV_INDENT."  ";

diff --git a/src/3d/symbols/qgslinevertexdata_p.h b/src/3d/symbols/qgslinevertexdata_p.h
@@ -55,6 +55,7 @@ class Qgs3DMapSettings;
  * Index zero is used for primitive restart (to separate two linestrings).
  *
  * It is expected that client code:
+ *
  * # calls init()
  * # calls addLineString() many times
  * # calls createGeometry()

diff --git a/src/core/layertree/qgslayertreemodel.h b/src/core/layertree/qgslayertreemodel.h
@@ -374,8 +374,10 @@ class CORE_EXPORT QgsLayerTreeModel : public QAbstractItemModel
     /**
      * Structure that stores tree representation of map layer's legend.
      * This structure is used only when the following requirements are met:
+     *
      * # tree legend representation is enabled in model (ShowLegendAsTree flag)
      * # some legend nodes have non-null parent rule key (accessible via data(ParentRuleKeyRole) method)
+     *
      * The tree structure (parents and children of each node) is extracted by analyzing nodes' parent rules.
      * \note not available in Python bindings
      */

diff --git a/src/core/pal/problem.h b/src/core/pal/problem.h
@@ -170,7 +170,7 @@ namespace pal
       int mTotalCandidates = 0;
 
       /**
-       * # candidates (all, including)
+       * Number of candidates (all, including)
        */
       int mAllNblp = 0;
 

diff --git a/src/core/qgscoordinatereferencesystem.h b/src/core/qgscoordinatereferencesystem.h
@@ -75,12 +75,11 @@ typedef void ( *CUSTOM_CRS_VALIDATION )( QgsCoordinateReferenceSystem & ) SIP_SK
  *
  * Most commonly one comes across two types of coordinate systems:
  *
- * # **Geographic coordinate systems** - based on a geodetic datum, normally with coordinates being
- *    latitude/longitude in degrees. The most common one is World Geodetic System 84 (WGS84).
- *
- * # **Projected coordinate systems** - based on a geodetic datum with coordinates projected to a plane,
- *    typically using meters or feet as units. Common projected coordinate systems are Universal
- *    Transverse Mercator or Albers Equal Area.
+ * # Geographic coordinate systems: based on a geodetic datum, normally with coordinates being
+ *   latitude/longitude in degrees. The most common one is World Geodetic System 84 (WGS84).
+ * # Projected coordinate systems: based on a geodetic datum with coordinates projected to a plane,
+ *   typically using meters or feet as units. Common projected coordinate systems are Universal
+ *   Transverse Mercator or Albers Equal Area.
  *
  * Internally QGIS uses proj library for all the math behind coordinate transformations, so in case
  * of any troubles with projections it is best to examine the PROJ representation within the object,
@@ -114,46 +113,44 @@ typedef void ( *CUSTOM_CRS_VALIDATION )( QgsCoordinateReferenceSystem & ) SIP_SK
  *
  * This section gives an overview of various supported CRS definition formats:
  *
- * # **Authority and Code.** Also referred to as OGC WMS format within QGIS as they have been widely
- *    used in OGC standards. These are encoded as `<auth>:<code>`, for example `EPSG:4326` refers
- *    to WGS84 system. EPSG is the most commonly used authority that covers a wide range
- *    of coordinate systems around the world.
+ * # Authority and Code: Also referred to as OGC WMS format within QGIS as they have been widely
+ *   used in OGC standards. These are encoded as `<auth>:<code>`, for example `EPSG:4326` refers
+ *   to WGS84 system. EPSG is the most commonly used authority that covers a wide range
+ *   of coordinate systems around the world.
  *
- *    An extended variant of this format is OGC URN. Syntax of URN for CRS definition is
- *    `urn:ogc:def:crs:<auth>:[<version>]:<code>`. This class can also parse URNs (versions
- *    are currently ignored). For example, WGS84 may be encoded as `urn:ogc:def:crs:OGC:1.3:CRS84`.
+ *   An extended variant of this format is OGC URN. Syntax of URN for CRS definition is
+ *   `urn:ogc:def:crs:<auth>:[<version>]:<code>`. This class can also parse URNs (versions
+ *   are currently ignored). For example, WGS84 may be encoded as `urn:ogc:def:crs:OGC:1.3:CRS84`.
  *
- *    QGIS adds support for "USER" authority that refers to IDs used internally in QGIS. This variant
- *    is best avoided or used with caution as the IDs are not permanent and they refer to different CRS
- *    on different machines or user profiles.
+ *   QGIS adds support for "USER" authority that refers to IDs used internally in QGIS. This variant
+ *   is best avoided or used with caution as the IDs are not permanent and they refer to different CRS
+ *   on different machines or user profiles.
  *
  *    \see authid()
- *    \see createFromOgcWmsCrs()
- *
- * # **PROJ string.** This is a string consisting of a series of key/value pairs in the following
- *    format: `+param1=value1 +param2=value2 [...]`. This is the format natively used by the
- *    underlying proj library. For example, the definition of WGS84 looks like this:
- *
- *    \code
- *    +proj=longlat +datum=WGS84 +no_defs
- *    \endcode
+ *   \see createFromOgcWmsCrs()
+ * # PROJ string: This is a string consisting of a series of key/value pairs in the following
+ *   format: `+param1=value1 +param2=value2 [...]`. This is the format natively used by the
+ *   underlying proj library. For example, the definition of WGS84 looks like this:
  *
- *    \see toProj()
- *    \see createFromProj()
+ *   \code
+ *   +proj=longlat +datum=WGS84 +no_defs
+ *   \endcode
  *
- * # **Well-known text (WKT).** Defined by Open Geospatial Consortium (OGC), this is another common
- *    format to define CRS. For WGS84 the OGC WKT definition is the following:
+ *   \see toProj()
+ *   \see createFromProj()
+ * # Well-known text (WKT): Defined by Open Geospatial Consortium (OGC), this is another common
+ *   format to define CRS. For WGS84 the OGC WKT definition is the following:
  *
- *        GEOGCS["WGS 84",
- *               DATUM["WGS_1984",
- *                 SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],
- *                 AUTHORITY["EPSG","6326"]],
- *               PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],
- *               UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],
- *               AUTHORITY["EPSG","4326"]]
+ *       GEOGCS["WGS 84",
+ *              DATUM["WGS_1984",
+ *                SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],
+ *                AUTHORITY["EPSG","6326"]],
+ *              PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],
+ *              UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],
+ *              AUTHORITY["EPSG","4326"]]
  *
- *    \see toWkt()
- *    \see createFromWkt()
+ *   \see toWkt()
+ *   \see createFromWkt()
  *
  * CRS Database and Custom CRS
  * ===========================