Convert documentation from epydoc to Sphinx

Signed-off-by: Simon McVittie <smcv@collabora.com>

7 files changed, 56 insertions, 70 deletions

diff --git a/dbus_bindings/bytes.c b/dbus_bindings/bytes.c
index b0ff817..af8188a 100644
--- a/dbus_bindings/bytes.c
+++ b/dbus_bindings/bytes.c
@@ -49,10 +49,10 @@ PyDoc_STRVAR(Byte_tp_doc,
 "\n"
 "   dbus.Byte(integer or str of length 1[, variant_level])\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a byte, this is represented in Python by a\n"
diff --git a/dbus_bindings/containers.c b/dbus_bindings/containers.c
index e364f98..165f6fc 100644
--- a/dbus_bindings/containers.c
+++ b/dbus_bindings/containers.c
@@ -44,7 +44,7 @@ PyDoc_STRVAR(Array_tp_doc,
 "\n"
 "    dbus.Array([iterable][, signature][, variant_level])\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
 "\n"
 "``signature`` is the D-Bus signature string for a single element of the\n"
 "array, or None. If not None it must represent a single complete type, the\n"
@@ -53,13 +53,6 @@ PyDoc_STRVAR(Array_tp_doc,
 "\n"
 "If None (the default), when the Array is sent over\n"
 "D-Bus, the item signature will be guessed from the first element.\n"
-"\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
-"    Indicates how many nested Variant containers this object\n"
-"    is contained in: if a message's wire format has a variant containing a\n"
-"    variant containing an array, this is represented in Python by an\n"
-"    Array with variant_level==2.\n"
 );
 
 static struct PyMemberDef Array_tp_members[] = {
@@ -68,8 +61,11 @@ static struct PyMemberDef Array_tp_members[] = {
      "instance)"},
     {"variant_level", T_LONG, offsetof(DBusPyArray, variant_level),
      READONLY,
-     "The number of nested variants wrapping the real data. "
-     "0 if not in a variant."},
+    "Indicates how many nested Variant containers this object\n"
+    "is contained in: if a message's wire format has a variant containing a\n"
+    "variant containing an array, this is represented in Python by an\n"
+    "Array with variant_level==2.\n"
+    },
     {NULL},
 };
 
@@ -277,7 +273,7 @@ PyDoc_STRVAR(Dict_tp_doc,
 "\n"
 "    Dictionary(mapping_or_iterable=(), signature=None, variant_level=0)\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
 "\n"
 "``signature`` is either a string or None. If a string, it must consist\n"
 "of exactly two complete type signatures, representing the 'key' type\n"
@@ -288,13 +284,6 @@ PyDoc_STRVAR(Dict_tp_doc,
 "If it is None (the default), when the Dictionary is sent over\n"
 "D-Bus, the key and value signatures will be guessed from an arbitrary\n"
 "element of the Dictionary.\n"
-"\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
-"    Indicates how many nested Variant containers this object\n"
-"    is contained in: if a message's wire format has a variant containing a\n"
-"    variant containing an array of DICT_ENTRY, this is represented in\n"
-"    Python by a Dictionary with variant_level==2.\n"
 );
 
 static struct PyMemberDef Dict_tp_members[] = {
@@ -303,8 +292,11 @@ static struct PyMemberDef Dict_tp_members[] = {
      "that of each value in this Dictionary, as a Signature instance."},
     {"variant_level", T_LONG, offsetof(DBusPyDict, variant_level),
      READONLY,
-     "The number of nested variants wrapping the real data. "
-     "0 if not in a variant."},
+    "Indicates how many nested Variant containers this object\n"
+    "is contained in: if a message's wire format has a variant containing a\n"
+    "variant containing a dictionary, this is represented in Python by a\n"
+    "Dictionary with variant_level==2.\n"
+    },
     {NULL},
 };
 
@@ -540,10 +532,10 @@ PyDoc_STRVAR(Struct_tp_doc,
 "If the signature is None (default) it will be guessed\n"
 "from the types of the items during construction.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a struct, this is represented in Python by a\n"
diff --git a/dbus_bindings/int.c b/dbus_bindings/int.c
index 66ad9e0..871a065 100644
--- a/dbus_bindings/int.c
+++ b/dbus_bindings/int.c
@@ -47,10 +47,10 @@ PyDoc_STRVAR(Boolean_tp_doc,
 "\n"
 "``value`` is converted to 0 or 1 as if by ``int(bool(value))``.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a boolean, this is represented in Python by a\n"
@@ -160,8 +160,8 @@ PyDoc_STRVAR(Int16_tp_doc,
 "\n"
 "    variant_level must be non-negative; the default is 0.\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
+".. py:attribute:: variant_level\n"
+"\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing an int16, this is represented in Python by an\n"
@@ -248,10 +248,10 @@ PyDoc_STRVAR(UInt16_tp_doc,
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a uint16, this is represented in Python by a\n"
@@ -340,10 +340,10 @@ PyDoc_STRVAR(Int32_tp_doc,
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing an int32, this is represented in Python by an\n"
@@ -433,10 +433,10 @@ PyDoc_STRVAR(UInt32_tp_doc,
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a uint32, this is represented in Python by a\n"
@@ -537,10 +537,10 @@ PyDoc_STRVAR(Int64_tp_doc,
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing an int64, this is represented in Python by an\n"
@@ -644,10 +644,10 @@ PyDoc_STRVAR(UInt64_tp_doc,
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a uint64, this is represented in Python by a\n"
diff --git a/dbus_bindings/message-append.c b/dbus_bindings/message-append.c
index d20b493..0480ceb 100644
--- a/dbus_bindings/message-append.c
+++ b/dbus_bindings/message-append.c
@@ -70,7 +70,8 @@ get_variant_level(PyObject *obj)
 }
 
 char dbus_py_Message_append__doc__[] = (
-"set_args(*args[, **kwargs])\n\n"
+"message.append(*args, **kwargs)\n"
+"\n"
 "Set the message's arguments from the positional parameter, according to\n"
 "the signature given by the ``signature`` keyword parameter.\n"
 "\n"
diff --git a/dbus_bindings/signature.c b/dbus_bindings/signature.c
index e3a555c..574968b 100644
--- a/dbus_bindings/signature.c
+++ b/dbus_bindings/signature.c
@@ -42,10 +42,10 @@ PyDoc_STRVAR(Signature_tp_doc,
 "``value`` must be a valid D-Bus signature (zero or more single complete\n"
 "types).\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing a signature, this is represented in Python by a\n"
diff --git a/dbus_bindings/string.c b/dbus_bindings/string.c
index 8363f98..32c1e31 100644
--- a/dbus_bindings/string.c
+++ b/dbus_bindings/string.c
@@ -129,19 +129,16 @@ PyTypeObject DBusPyUTF8String_Type = {
 /* Object path ====================================================== */
 
 PyDoc_STRVAR(ObjectPath_tp_doc,
-"A D-Bus object path, such as '/com/example/MyApp/Documents/abc'.\n"
+"dbus.ObjectPath(path: str[, variant_level: int=0])\n"
+"A D-Bus object path, such as ``/com/example/MyApp/Documents/abc``.\n"
 "\n"
-"ObjectPath is a subtype of str, and object-paths behave like strings.\n"
-"\n"
-"Constructor::\n"
-"\n"
-"    dbus.ObjectPath(path: str, variant_level: int) -> ObjectPath\n"
+"ObjectPath is a subtype of :py:class:`str`, and object-paths behave like strings.\n"
 "\n"
 "path must be an ASCII string following the syntax of object paths.\n"
 "variant_level must be non-negative; the default is 0.\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
+".. py:attribute:: variant_level\n"
+"\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing an object path, this is represented in Python by an\n"
@@ -223,20 +220,16 @@ PyDoc_STRVAR(String_tp_doc,
 "    String(value: str or unicode[, variant_level: int]) -> String\n"
 "\n"
 "variant_level must be non-negative; the default is 0.\n"
-"\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
-"    Indicates how many nested Variant containers this object\n"
-"    is contained in: if a message's wire format has a variant containing a\n"
-"    variant containing a string, this is represented in Python by a\n"
-"    String or UTF8String with variant_level==2.\n"
 );
 
 static PyMemberDef String_tp_members[] = {
     {"variant_level", T_LONG, offsetof(DBusPyString, variant_level),
      READONLY,
-     "The number of nested variants wrapping the real data. "
-     "0 if not in a variant"},
+    "Indicates how many nested Variant containers this object\n"
+    "is contained in: if a message's wire format has a variant containing a\n"
+    "variant containing an array, this is represented in Python by a\n"
+    "String or UTF8String with variant_level==2.\n"
+    },
     {NULL},
 };
 
diff --git a/dbus_bindings/unixfd.c b/dbus_bindings/unixfd.c
index 648dd2c..62a5acb 100644
--- a/dbus_bindings/unixfd.c
+++ b/dbus_bindings/unixfd.c
@@ -42,10 +42,10 @@ PyDoc_STRVAR(UnixFd_tp_doc,
 "UnixFd keeps a dup() (duplicate) of the supplied file descriptor. The\n"
 "caller remains responsible for closing the original fd.\n"
 "\n"
-"``variant_level`` must be non-negative; the default is 0.\n"
+":py:attr:`variant_level` must be non-negative; the default is 0.\n"
+"\n"
+".. py:attribute:: variant_level\n"
 "\n"
-":IVariables:\n"
-"  `variant_level` : int\n"
 "    Indicates how many nested Variant containers this object\n"
 "    is contained in: if a message's wire format has a variant containing a\n"
 "    variant containing an Unix Fd, this is represented in Python by an\n"