Skip to content
Permalink
Browse files

Some fixes to numbered list handling in dox/PyQGIS API

  • Loading branch information
nyalldawson committed Jun 14, 2020
1 parent 1ef12a0 commit 74400c7ff88d563dad74dad41860f9b603214973
@@ -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 );
@@ -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",
@@ -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
@@ -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
@@ -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.

@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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." ";
@@ -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()
@@ -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
*/
@@ -170,7 +170,7 @@ namespace pal
int mTotalCandidates = 0;

/**
* # candidates (all, including)
* Number of candidates (all, including)
*/
int mAllNblp = 0;

@@ -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
* ===========================

0 comments on commit 74400c7

Please sign in to comment.
You can’t perform that action at this time.