try rewriting gi-docgen refs

Author: jcupitt

README.rst

@@ -195,7 +195,6 @@ Local user install:
 .. code-block:: shell
 
     $ pip install -e .[binary]
-    $ pypy -m pip --user -e .
 
 Run all tests:
 

examples/gen-enums.py

@@ -37,6 +37,58 @@ def remove_prefix(enum_str):
     return enum_str
 
 
+def rewrite_references(string):
+    """Rewrite a gi-docgen references to RST style.
+
+    gi-docgen references look like this:
+
+        [func@version]
+        [class@Image]
+        [func@Image.bandjoin]
+        [meth@Image.add]
+        [ctor@Image.new_from_file]
+        [enum@SdfShape]
+        [enum@Vips.SdfShape.CIRCLE]
+
+    we look for the approximate patterns and rewrite in RST style, so:
+
+        :meth:`.version`
+        :class:`.Image`
+        :meth:`.Image.bandjoin`
+        :meth:`.Image.new_from_file`
+        :class:`.enums.SdfShape`
+        :class:`.enums.SdfShape.CIRCLE`
+    """
+
+    import re
+    while True:
+        match = re.search(r"\[(.*?)@(.*?)\]", string)
+        if not match:
+            break
+
+        before = string[0:match.span(0)[0]]
+        type = match[1]
+        target = match[2]
+        after = string[match.span(0)[1]:]
+
+        if type in ["ctor", "meth", "method", "func"]:
+            python_type = "meth"
+        elif type in ["class", "enum", "flags"]:
+            python_type = "class"
+        else:
+            raise Exception(f'type "{type}" is unknown')
+
+        match = re.match("Vips.(.*)", target)
+        if match:
+            target = match[1]
+
+        if type == "enum":
+            target = f"enums.{target}"
+
+        string = f"{before}:{python_type}:`.{target}`{after}"
+
+    return string
+
 def generate_enums():
     all_nicknames = []
 
@@ -70,7 +122,7 @@ def add_nickname(gtype, a, b):
         print(f'    """{python_name}.')
         if enum_doc is not None:
             print('')
-            print(f'{enum_doc.text}')
+            print(f'{rewrite_references(enum_doc.text)}')
         print('')
         print('Attributes:')
         print('')
@@ -79,7 +131,7 @@ def add_nickname(gtype, a, b):
             member = node.find(f"goi:member[@name='{python_name}']", namespace)
             member_doc = member.find("goi:doc", namespace)
             if member_doc is not None:
-                text = member_doc.text
+                text = rewrite_references(member_doc.text)
                 print(f'    {python_name.upper()} (str): {text}')
                 print('')
         print('    """')
@@ -123,7 +175,7 @@ def add_nickname(gtype, a, b):
         print(f'    """{python_name}.')
         if enum_doc is not None:
             print('')
-            print(f'{enum_doc.text}')
+            print(f'{rewrite_references(enum_doc.text)}')
         print('')
         print('Attributes:')
         print('')
@@ -133,7 +185,7 @@ def add_nickname(gtype, a, b):
             member_doc = member.find("goi:doc", namespace)
             if member_doc is not None:
                 text = member_doc.text
-                print(f'    {python_name.upper()} (int): {text}')
+                print(f'    {python_name.upper()} (int): {rewrite_references(text)}')
                 print('')
         print('    """')
         print('')

pyvips/enums.py

@@ -8,7 +8,7 @@ class BandFormat(object):
 The format used for each band element.
 
 Each corresponds to a native C type for the current machine. For example,
-[enum@Vips.BandFormat.USHORT] is `unsigned short`.
+:class:`.enums.BandFormat.USHORT` is `unsigned short`.
 
 Attributes:
 
@@ -52,7 +52,7 @@ class BandFormat(object):
 class BlendMode(object):
     """BlendMode.
 
-The various Porter-Duff and PDF blend modes. See [func@Image.composite],
+The various Porter-Duff and PDF blend modes. See :meth:`.Image.composite`,
 for example.
 
 The Cairo docs have a nice explanation of all the blend modes:
@@ -250,13 +250,13 @@ class Interpretation(object):
 class DemandStyle(object):
     """DemandStyle.
 
-See [method@Image.pipelinev]. Operations can hint
+See :meth:`.Image.pipelinev`. Operations can hint
 the kind of demand geometry they prefer
 to the VIPS image IO system.
 
 These demand styles are given below in order of increasing
 specialisation.  When demanding output from a pipeline,
-[method@Image.generate]
+:meth:`.Image.generate`
 will use the most general style requested by the operations
 in the pipeline.
 
@@ -267,18 +267,18 @@ class DemandStyle(object):
 @VIPS_DEMAND_STYLE_FATSTRIP -- This operation would like to output strips
 the width of the image and as high as possible. This option is suitable
 for area operations which do not violently transform coordinates, such
-as [method@Image.conv].
+as :meth:`.Image.conv`.
 
 @VIPS_DEMAND_STYLE_THINSTRIP -- This operation would like to output strips
 the width of the image and a few pels high. This option is suitable for
 point-to-point operations, such as those in the arithmetic package.
 
 @VIPS_DEMAND_STYLE_ANY -- This image is not being demand-read from a disc
 file (even indirectly) so any demand style is OK. It's used for things like
-[ctor@Image.black] where the pixels are calculated.
+:meth:`.Image.black` where the pixels are calculated.
 
 ::: seealso
-    [method@Image.pipelinev].
+    :meth:`.Image.pipelinev`.
 
 Attributes:
 
@@ -504,7 +504,7 @@ class OperationComplexget(object):
 class Combine(object):
     """Combine.
 
-How to combine values. See [method@Image.compass], for example.
+How to combine values. See :meth:`.Image.compass`, for example.
 
 Attributes:
 
@@ -524,8 +524,8 @@ class Combine(object):
 class Access(object):
     """Access.
 
-The type of access an operation has to supply. See [method@Image.tilecache]
-and [class@Foreign].
+The type of access an operation has to supply. See :meth:`.Image.tilecache`
+and :class:`.Foreign`.
 
 @VIPS_ACCESS_RANDOM means requests can come in any order.
 
@@ -548,7 +548,7 @@ class Access(object):
 class Extend(object):
     """Extend.
 
-See [method@Image.embed], [method@Image.conv], [method@Image.affine] and so on.
+See :meth:`.Image.embed`, :meth:`.Image.conv`, :meth:`.Image.affine` and so on.
 
 When the edges of an image are extended, you can specify
 how you want the extension done.
@@ -571,7 +571,7 @@ class Extend(object):
 keep these frozen for back compat with vips7.
 
 ::: seealso
-    [method@Image.embed].
+    :meth:`.Image.embed`.
 
 Attributes:
 
@@ -600,7 +600,7 @@ class Extend(object):
 class CompassDirection(object):
     """CompassDirection.
 
-A direction on a compass. Used for [method@Image.gravity], for example.
+A direction on a compass. Used for :meth:`.Image.gravity`, for example.
 
 Attributes:
 
@@ -638,13 +638,13 @@ class CompassDirection(object):
 class Direction(object):
     """Direction.
 
-See [method@Image.flip], [method@Image.join] and so on.
+See :meth:`.Image.flip`, :meth:`.Image.join` and so on.
 
-Operations like [method@Image.flip] need to be told whether to flip left-right or
+Operations like :meth:`.Image.flip` need to be told whether to flip left-right or
 top-bottom.
 
 ::: seealso
-    [method@Image.flip], [method@Image.join].
+    :meth:`.Image.flip`, :meth:`.Image.join`.
 
 Attributes:
 
@@ -661,13 +661,13 @@ class Direction(object):
 class Align(object):
     """Align.
 
-See [method@Image.join] and so on.
+See :meth:`.Image.join` and so on.
 
-Operations like [method@Image.join] need to be told whether to align images on the
+Operations like :meth:`.Image.join` need to be told whether to align images on the
 low or high coordinate edge, or centre.
 
 ::: seealso
-    [method@Image.join].
+    :meth:`.Image.join`.
 
 Attributes:
 
@@ -688,15 +688,15 @@ class Interesting(object):
     """Interesting.
 
 Pick the algorithm vips uses to decide image "interestingness". This is used
-by [method@Image.smartcrop], for example, to decide what parts of the image to
+by :meth:`.Image.smartcrop`, for example, to decide what parts of the image to
 keep.
 
 #VIPS_INTERESTING_NONE and #VIPS_INTERESTING_LOW mean the same -- the
 crop is positioned at the top or left. #VIPS_INTERESTING_HIGH positions at
 the bottom or right.
 
 ::: seealso
-    [method@Image.smartcrop].
+    :meth:`.Image.smartcrop`.
 
 Attributes:
 
@@ -728,12 +728,12 @@ class Interesting(object):
 class Angle(object):
     """Angle.
 
-See [method@Image.rot] and so on.
+See :meth:`.Image.rot` and so on.
 
 Fixed rotate angles.
 
 ::: seealso
-    [method@Image.rot].
+    :meth:`.Image.rot`.
 
 Attributes:
 
@@ -756,12 +756,12 @@ class Angle(object):
 class Angle45(object):
     """Angle45.
 
-See [method@Image.rot45] and so on.
+See :meth:`.Image.rot45` and so on.
 
 Fixed rotate angles.
 
 ::: seealso
-    [method@Image.rot45].
+    :meth:`.Image.rot45`.
 
 Attributes:
 
@@ -816,11 +816,11 @@ class Precision(object):
 class TextWrap(object):
     """TextWrap.
 
-Sets the word wrapping style for [ctor@Image.text] when used with a maximum
+Sets the word wrapping style for :meth:`.Image.text` when used with a maximum
 width.
 
 ::: seealso
-    [ctor@Image.text].
+    :meth:`.Image.text`.
 
 Attributes:
 
@@ -846,7 +846,7 @@ class SdfShape(object):
 The SDF to generate,
 
 ::: seealso
-    [ctor@Image.sdf].
+    :meth:`.Image.sdf`.
 
 Attributes:
 
@@ -1257,8 +1257,8 @@ class Kernel(object):
 class PCS(object):
     """PCS.
 
-Pick a Profile Connection Space for [method@Image.icc_import] and
-[method@Image.icc_export]. LAB is usually best, XYZ can be more convenient in some
+Pick a Profile Connection Space for :meth:`.Image.icc_import` and
+:meth:`.Image.icc_export`. LAB is usually best, XYZ can be more convenient in some
 cases.
 
 Attributes: