[sipify] Convert "\a arg" to "arg" when processing Docstrings

Allows argument names to be highlighted in Python docs
qgis · Apr 17, 2017 · eff5a82 · eff5a82
1 parent e4d6bbf
commit eff5a82
Show file tree

Hide file tree

Showing 14 changed files with 47 additions and 47 deletions.
diff --git a/python/core/geometry/qgsbox3d.sip b/python/core/geometry/qgsbox3d.sip
@@ -39,14 +39,14 @@ class QgsBox3d
 
     void setXMinimum( double x );
 %Docstring
- Sets the minimum x value.
+ Sets the minimum ``x`` value.
  \see xMinimum()
  \see setXMaximum()
 %End
 
     void setXMaximum( double x );
 %Docstring
- Sets the maximum x value.
+ Sets the maximum ``x`` value.
  \see xMaximum()
  \see setXMinimum()
 %End
@@ -69,14 +69,14 @@ class QgsBox3d
 
     void setYMinimum( double y );
 %Docstring
- Sets the minimum y value.
+ Sets the minimum ``y`` value.
  \see yMinimum()
  \see setYMaximum()
 %End
 
     void setYMaximum( double y );
 %Docstring
- Sets the maximum y value.
+ Sets the maximum ``y`` value.
  \see yMaximum()
  \see setYMinimum()
 %End
@@ -99,14 +99,14 @@ class QgsBox3d
 
     void setZMinimum( double z );
 %Docstring
- Sets the minimum z value.
+ Sets the minimum ``z`` value.
  \see zMinimum()
  \see setZMaximum()
 %End
 
     void setZMaximum( double z );
 %Docstring
- Sets the maximum z value.
+ Sets the maximum ``z`` value.
  \see zMaximum()
  \see setZMinimum()
 %End
@@ -182,7 +182,7 @@ class QgsBox3d
 
     bool contains( const QgsPointV2 &point ) const;
 %Docstring
- Returns true when box contains a point.
+ Returns true when box contains a ``point``.
 
  If the point is a 2D point (no z-coordinate), then the containment test
  will be performed on the x/y extent of the box only.

diff --git a/python/core/geometry/qgsrectangle.sip b/python/core/geometry/qgsrectangle.sip
@@ -293,7 +293,7 @@ Copy constructor
     QgsBox3d toBox3d( double zMin, double zMax ) const;
 %Docstring
  Converts the rectangle to a 3D box, with the specified
- zMin and zMax z values.
+ ``zMin`` and ``zMax`` z values.
 .. versionadded:: 3.0
  :rtype: QgsBox3d
 %End

diff --git a/python/core/processing/qgsprocessingprovider.sip b/python/core/processing/qgsprocessingprovider.sip
@@ -142,7 +142,7 @@ class QgsProcessingProvider : QObject
 
     const QgsProcessingAlgorithm *algorithm( const QString &name ) const;
 %Docstring
- Returns the matching algorithm by name, or a None if no matching
+ Returns the matching algorithm by ``name``, or a None if no matching
  algorithm is contained by this provider.
  \see algorithms()
  :rtype: QgsProcessingAlgorithm
@@ -167,7 +167,7 @@ class QgsProcessingProvider : QObject
 
     bool addAlgorithm( QgsProcessingAlgorithm *algorithm /Transfer/ );
 %Docstring
- Adds an algorithm to the provider. Ownership of the algorithm is transferred to the provider.
+ Adds an ``algorithm`` to the provider. Ownership of the algorithm is transferred to the provider.
  :rtype: bool
 %End
 

diff --git a/python/core/processing/qgsprocessingutils.sip b/python/core/processing/qgsprocessingutils.sip
@@ -26,10 +26,10 @@ class QgsProcessingUtils
 
     static QList< QgsRasterLayer * > compatibleRasterLayers( QgsProject *project, bool sort = true );
 %Docstring
- Returns a list of raster layers from a project which are compatible with the processing
+ Returns a list of raster layers from a ``project`` which are compatible with the processing
  framework.
 
- If the sort argument is true then the layers will be sorted by their QgsMapLayer.name()
+ If the ``sort`` argument is true then the layers will be sorted by their QgsMapLayer.name()
  value.
  \see compatibleVectorLayers()
  \see compatibleLayers()
@@ -40,14 +40,14 @@ class QgsProcessingUtils
         const QList< QgsWkbTypes::GeometryType > &geometryTypes = QList< QgsWkbTypes::GeometryType >(),
         bool sort = true );
 %Docstring
- Returns a list of vector layers from a project which are compatible with the processing
+ Returns a list of vector layers from a ``project`` which are compatible with the processing
  framework.
 
- If the geometryTypes list is non-empty then the layers will be sorted so that only
- layers with geometry types included in the list will be returned. Leaving the geometryTypes
+ If the ``geometryTypes`` list is non-empty then the layers will be sorted so that only
+ layers with geometry types included in the list will be returned. Leaving the ``geometryTypes``
  list empty will cause all vector layers, regardless of their geometry type, to be returned.
 
- If the sort argument is true then the layers will be sorted by their QgsMapLayer.name()
+ If the ``sort`` argument is true then the layers will be sorted by their QgsMapLayer.name()
  value.
  \see compatibleRasterLayers()
  \see compatibleLayers()
@@ -56,10 +56,10 @@ class QgsProcessingUtils
 
     static QList< QgsMapLayer * > compatibleLayers( QgsProject *project, bool sort = true );
 %Docstring
- Returns a list of map layers from a project which are compatible with the processing
+ Returns a list of map layers from a ``project`` which are compatible with the processing
  framework.
 
- If the sort argument is true then the layers will be sorted by their QgsMapLayer.name()
+ If the ``sort`` argument is true then the layers will be sorted by their QgsMapLayer.name()
  value.
  \see compatibleRasterLayers()
  \see compatibleVectorLayers()
@@ -69,12 +69,12 @@ class QgsProcessingUtils
 
     static QgsMapLayer *mapLayerFromProject( const QString &string, QgsProject *project );
 %Docstring
- Interprets a string as a map layer from a project.
+ Interprets a ``string`` as a map layer from a project.
 
  This method attempts to match a string to a project map layer, using
  first the layer ID, then layer names, and finally layer source.
  If the string matches a normalized version of any layer source
- for layers in the specified project, then those matching layers will be
+ for layers in the specified ``project``, then those matching layers will be
  returned.
  \see mapLayerFromString()
  :rtype: QgsMapLayer
@@ -83,7 +83,7 @@ class QgsProcessingUtils
     static QgsMapLayer *mapLayerFromString( const QString &string ) /Factory/;
 %Docstring
  Interprets a string as a map layer. The method will attempt to
- load a layer matching the passed string. E.g. if the string is a file path,
+ load a layer matching the passed ``string``. E.g. if the string is a file path,
  then the layer at this file path will be loaded.
  The caller takes responsibility for deleting the returned map layer.
  \see mapLayerFromProject()
@@ -92,7 +92,7 @@ class QgsProcessingUtils
 
     static QString normalizeLayerSource( const QString &source );
 %Docstring
- Normalizes a layer source string for safe comparison across different
+ Normalizes a layer ``source`` string for safe comparison across different
  operating system environments.
  :rtype: str
 %End

diff --git a/python/core/qgsanimatedicon.sip b/python/core/qgsanimatedicon.sip
@@ -21,7 +21,7 @@ class QgsAnimatedIcon : QObject
 
     QgsAnimatedIcon( const QString &iconPath = QString(), QObject *parent = 0 );
 %Docstring
- Create a new animated icon. Optionally, the iconPath can already be specified.
+ Create a new animated icon. Optionally, the ``iconPath`` can already be specified.
 %End
 
     QString iconPath() const;

diff --git a/python/core/qgsmaplayer.sip b/python/core/qgsmaplayer.sip
@@ -865,7 +865,7 @@ Time stamp of data source in the moment when data/metadata were loaded by provid
 %Docstring
  Will advise the map canvas (and any other interested party) that this layer requires to be repainted.
  Will emit a repaintRequested() signal.
- If deferredUpdate is true then the layer will only be repainted when the canvas is next
+ If ``deferredUpdate`` is true then the layer will only be repainted when the canvas is next
  re-rendered, and will not trigger any canvas redraws itself.
 
 .. note::
@@ -913,7 +913,7 @@ Emit a signal that layer's CRS has been reset
 %Docstring
  By emitting this signal the layer tells that either appearance or content have been changed
  and any view showing the rendered layer should refresh itself.
- If deferredUpdate is true then the layer will only be repainted when the canvas is next
+ If ``deferredUpdate`` is true then the layer will only be repainted when the canvas is next
  re-rendered, and will not trigger any canvas redraws itself.
 %End
 

diff --git a/python/core/qgsofflineediting.sip b/python/core/qgsofflineediting.sip
@@ -63,8 +63,8 @@ Synchronize to remote layers
 %Docstring
  Is emitted whenever a new layer is being processed.
  It is possible to estimate the progress of the complete operation by
- comparing the index of the current layer to the total amount
- numLayers.
+ comparing the index of the current ``layer`` to the total amount
+ ``numLayers``.
 %End
 
     void progressModeSet( QgsOfflineEditing::ProgressMode mode, int maximum );

diff --git a/python/core/qgspropertytransformer.sip b/python/core/qgspropertytransformer.sip
@@ -44,7 +44,7 @@ class QgsCurveTransform
 
     QgsCurveTransform( const QList< QgsPoint > &controlPoints );
 %Docstring
- Constructs a QgsCurveTransform using a specified list of controlPoints.
+ Constructs a QgsCurveTransform using a specified list of ``controlPoints``.
  Behavior is undefined if duplicate x values exist in the control points
  list.
 %End
@@ -88,13 +88,13 @@ class QgsCurveTransform
 
     double y( double x ) const;
 %Docstring
- Returns the mapped y value corresponding to the specified x value.
+ Returns the mapped y value corresponding to the specified ``x`` value.
  :rtype: float
 %End
 
     QVector< double > y( const QVector< double > &x ) const;
 %Docstring
- Returns a list of y values corresponding to a list of x values.
+ Returns a list of y values corresponding to a list of ``x`` values.
  Calling this method is faster then calling the double variant multiple
  times.
  :rtype: list of float
@@ -265,7 +265,7 @@ class QgsPropertyTransformer
     void setCurveTransform( QgsCurveTransform *transform /Transfer/ );
 %Docstring
  Sets a curve transform to apply to input values before they are transformed
- by the individual transform subclasses. Ownership of transform is transferred
+ by the individual transform subclasses. Ownership of ``transform`` is transferred
  to the property transformer.
  \see curveTransform()
 %End
@@ -281,7 +281,7 @@ class QgsPropertyTransformer
 
     virtual QString toExpression( const QString &baseExpression ) const = 0;
 %Docstring
- Converts the transformer to a QGIS expression string. The baseExpression string consists
+ Converts the transformer to a QGIS expression string. The ``baseExpression`` string consists
  of a sub-expression reflecting the parent property's state.
  :rtype: str
 %End
@@ -306,7 +306,7 @@ class QgsPropertyTransformer
     double transformNumeric( double input ) const;
 %Docstring
  Applies base class numeric transformations. Derived classes should call this
- to transform an input numeric value before they apply any transform to the result.
+ to transform an ``input`` numeric value before they apply any transform to the result.
  This applies any curve transforms which may exist on the transformer.
  :rtype: float
 %End
@@ -371,7 +371,7 @@ class QgsGenericNumericTransformer : QgsPropertyTransformer
 
     double value( double input ) const;
 %Docstring
- Calculates the size corresponding to a specific input value.
+ Calculates the size corresponding to a specific ``input`` value.
  :return: calculated size using size scale transformer's parameters and type
  :rtype: float
 %End
@@ -678,7 +678,7 @@ Copy constructor
 
     void setRampName( const QString &name );
 %Docstring
- Sets the color ramp's name. The ramp name must be set to match
+ Sets the color ramp's ``name``. The ramp name must be set to match
  a color ramp available in the style database for conversion to expression
  to work correctly.
  \see rampName()

diff --git a/python/core/raster/qgsrasterfilewritertask.sip b/python/core/raster/qgsrasterfilewritertask.sip
@@ -29,9 +29,9 @@ class QgsRasterFileWriterTask : QgsTask
                              const QgsRectangle &outputExtent,
                              const QgsCoordinateReferenceSystem &crs );
 %Docstring
- Constructor for QgsRasterFileWriterTask. Takes a source writer,
- columns, rows, outputExtent and destination crs.
- Ownership of the pipe is transferred to the writer task, and will
+ Constructor for QgsRasterFileWriterTask. Takes a source ``writer``,
+ ``columns``, ``rows``, ``outputExtent`` and destination ``crs``.
+ Ownership of the ``pipe`` is transferred to the writer task, and will
  be deleted when the task completes.
 %End
 
@@ -41,14 +41,14 @@ class QgsRasterFileWriterTask : QgsTask
 
     void writeComplete( const QString &outputUrl );
 %Docstring
- Emitted when writing the layer is successfully completed. The outputUrl
+ Emitted when writing the layer is successfully completed. The ``outputUrl``
  parameter indicates the file path for the written file(s).
 %End
 
     void errorOccurred( int error );
 %Docstring
  Emitted when an error occurs which prevented the file being written (or if
- the task is canceled). The writing error will be reported.
+ the task is canceled). The writing ``error`` will be reported.
 %End
 
   protected:

diff --git a/python/gui/qgsmessagelogviewer.sip b/python/gui/qgsmessagelogviewer.sip
@@ -31,7 +31,7 @@ class QgsMessageLogViewer: QDialog
 
     void logMessage( const QString &message, const QString &tag, QgsMessageLog::MessageLevel level );
 %Docstring
- Logs a message to the viewer.
+ Logs a ``message`` to the viewer.
 %End
 
   protected:

diff --git a/python/gui/qgsoptionswidgetfactory.sip b/python/gui/qgsoptionswidgetfactory.sip
@@ -66,7 +66,7 @@ Constructor
 
     void setIcon( const QIcon &icon );
 %Docstring
- Set the icon to show in the interface for the factory object.
+ Set the ``icon`` to show in the interface for the factory object.
  \see icon()
 %End
 
@@ -79,7 +79,7 @@ Constructor
 
     void setTitle( const QString &title );
 %Docstring
- Set the title for the interface.
+ Set the ``title`` for the interface.
  \see title()
 %End
 

diff --git a/python/gui/symbology-ng/characterwidget.sip b/python/gui/symbology-ng/characterwidget.sip
@@ -61,7 +61,7 @@ class CharacterWidget : QWidget
 
     void setFont( const QFont &font );
 %Docstring
- Sets the font to show in the widget.
+ Sets the ``font`` to show in the widget.
  \see font()
 .. versionadded:: 3.0
 %End
@@ -88,7 +88,7 @@ class CharacterWidget : QWidget
 
     void setCharacter( QChar character );
 %Docstring
- Sets the currently selected character in the widget.
+ Sets the currently selected ``character`` in the widget.
  \see character()
  \see characterSelected()
 %End

diff --git a/scripts/sipify.pl b/scripts/sipify.pl
@@ -15,7 +15,7 @@ sub processDoxygenLine
 {
     my $line = $_[0];
     # remove \a formatting
-    $line =~ s/\\a //g;
+    $line =~ s/\\a (.+?)\b/``$1``/g;
     # replace :: with . (changes c++ style namespace/class directives to Python style)
     $line =~ s/::/./g;
     # replace nullptr with None (nullptr means nothing to Python devs)

diff --git a/tests/scripts/sipifyheader.expected.sip b/tests/scripts/sipifyheader.expected.sip
@@ -140,7 +140,7 @@ Factory annotation
     void LongDocStringMethodWithBrief();
 %Docstring
  some brief
- My long doc string
+ My long doc ``string``
  is not very interesting!
  Here's some comment mentioning another class QgsAutoAwesomemater.makeLessAwesome.
 %End