Merge pull request #543 from ploxiln/sphinx3

doc: compatibility with Sphinx-3

CHANGES

@@ -8,7 +8,7 @@ Released 2020-05-07
   - Include `jansson_version_str()` and `jansson_version_cmp()` in
     shared library. (#534)
 
-  - Include `scripts/` in tarball. (#535)
+  - Include ``scripts/`` in tarball. (#535)
 
 
 Version 2.13
@@ -127,7 +127,7 @@ Released 2018-02-09
 
   - Work around gcc's -Wimplicit-fallthrough.
 
-  - Fix CMake detection of `sys/types.h` header (#375).
+  - Fix CMake detection of ``sys/types.h`` header (#375).
 
   - Fix `jansson.pc` generated by CMake to be more consistent with the one
     generated using GNU Autotools (#368).

doc/apiref.rst

@@ -145,33 +145,33 @@ Type
 .. function:: int json_typeof(const json_t *json)
 
    Return the type of the JSON value (a :type:`json_type` cast to
-   :type:`int`). *json* MUST NOT be *NULL*. This function is actually
+   ``int``). *json* MUST NOT be *NULL*. This function is actually
    implemented as a macro for speed.
 
-.. function:: json_is_object(const json_t *json)
-               json_is_array(const json_t *json)
-               json_is_string(const json_t *json)
-               json_is_integer(const json_t *json)
-               json_is_real(const json_t *json)
-               json_is_true(const json_t *json)
-               json_is_false(const json_t *json)
-               json_is_null(const json_t *json)
+.. function:: int json_is_object(const json_t *json)
+              int json_is_array(const json_t *json)
+              int json_is_string(const json_t *json)
+              int json_is_integer(const json_t *json)
+              int json_is_real(const json_t *json)
+              int json_is_true(const json_t *json)
+              int json_is_false(const json_t *json)
+              int json_is_null(const json_t *json)
 
    These functions (actually macros) return true (non-zero) for values
    of the given type, and false (zero) for values of other types and
    for *NULL*.
 
-.. function:: json_is_number(const json_t *json)
+.. function:: int json_is_number(const json_t *json)
 
    Returns true for values of types ``JSON_INTEGER`` and
    ``JSON_REAL``, and false for other types and for *NULL*.
 
-.. function:: json_is_boolean(const json_t *json)
+.. function:: int json_is_boolean(const json_t *json)
 
    Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
    for values of other types and for *NULL*.
 
-.. function:: json_boolean_value(const json_t *json)
+.. function:: int json_boolean_value(const json_t *json)
 
    Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE``
    and 0 otherwise.
@@ -594,7 +594,7 @@ A JSON array is an ordered collection of other JSON values.
    Appends all elements in *other_array* to the end of *array*.
    Returns 0 on success and -1 on error.
 
-.. function:: json_array_foreach(array, index, value)
+.. function:: void json_array_foreach(array, index, value)
 
    Iterate over every element of ``array``, running the block
    of code that follows each time with the proper values set to
@@ -732,11 +732,11 @@ allowed in object keys.
    recursively merged with the corresponding values in *object* if they are also
    objects, instead of overwriting them. Returns 0 on success or -1 on error.
 
-.. function:: json_object_foreach(object, key, value)
+.. function:: void json_object_foreach(object, key, value)
 
    Iterate over every key-value pair of ``object``, running the block
    of code that follows each time with the proper values set to
-   variables ``key`` and ``value``, of types :type:`const char *` and
+   variables ``key`` and ``value``, of types ``const char *`` and
    :type:`json_t *` respectively. Example::
 
        /* obj is a JSON object */
@@ -764,7 +764,7 @@ allowed in object keys.
    .. versionadded:: 2.3
 
 
-.. function:: json_object_foreach_safe(object, tmp, key, value)
+.. function:: void json_object_foreach_safe(object, tmp, key, value)
 
    Like :func:`json_object_foreach()`, but it's safe to call
    ``json_object_del(object, key)`` during iteration. You need to pass
@@ -1488,17 +1488,17 @@ arguments.
     Output a JSON null value. No argument is consumed.
 
 ``b`` (boolean) [int]
-    Convert a C :type:`int` to JSON boolean value. Zero is converted
+    Convert a C ``int`` to JSON boolean value. Zero is converted
     to ``false`` and non-zero to ``true``.
 
 ``i`` (integer) [int]
-    Convert a C :type:`int` to JSON integer.
+    Convert a C ``int`` to JSON integer.
 
 ``I`` (integer) [json_int_t]
     Convert a C :type:`json_int_t` to JSON integer.
 
 ``f`` (real) [double]
-    Convert a C :type:`double` to JSON real.
+    Convert a C ``double`` to JSON real.
 
 ``o`` (any value) [json_t \*]
     Output any given JSON value as-is. If the value is added to an
@@ -1625,20 +1625,20 @@ type whose address should be passed.
     Expect a JSON null value. Nothing is extracted.
 
 ``b`` (boolean) [int]
-    Convert a JSON boolean value to a C :type:`int`, so that ``true``
+    Convert a JSON boolean value to a C ``int``, so that ``true``
     is converted to 1 and ``false`` to 0.
 
 ``i`` (integer) [int]
-    Convert a JSON integer to C :type:`int`.
+    Convert a JSON integer to C ``int``.
 
 ``I`` (integer) [json_int_t]
     Convert a JSON integer to C :type:`json_int_t`.
 
 ``f`` (real) [double]
-    Convert a JSON real to C :type:`double`.
+    Convert a JSON real to C ``double``.
 
 ``F`` (integer or real) [double]
-    Convert a JSON number (integer or real) to C :type:`double`.
+    Convert a JSON number (integer or real) to C ``double``.
 
 ``o`` (any value) [json_t \*]
     Store a JSON value with no conversion to a :type:`json_t` pointer.

doc/ext/refcounting.py

@@ -24,8 +24,8 @@
 """
 
 from docutils import nodes
+from docutils.parsers.rst import Directive
 
-class refcounting(nodes.emphasis): pass
 
 def visit(self, node):
     self.visit_emphasis(node)
@@ -40,16 +40,25 @@ def html_depart(self, node):
     self.body.append('</em>')
 
 
-def refcounting_directive(name, arguments, options, content, lineno,
-                   content_offset, block_text, state, state_machine):
-    if arguments[0] == 'borrow':
-        text = 'Return value: Borrowed reference.'
-    elif arguments[0] == 'new':
-        text = 'Return value: New reference.'
-    else:
-        raise Error('Valid arguments: new, borrow')
+class refcounting(nodes.emphasis):
+    pass
+
+class refcounting_directive(Directive):
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+
+    def run(self):
+        if self.arguments[0] == 'borrow':
+            text = 'Return value: Borrowed reference.'
+        elif self.arguments[0] == 'new':
+            text = 'Return value: New reference.'
+        else:
+            raise Error('Valid arguments: new, borrow')
+
+        return [refcounting(text, text)]
 
-    return [refcounting(text, text)]
 
 def setup(app):
     app.add_node(refcounting,
@@ -57,4 +66,4 @@ def setup(app):
                  latex=(visit, depart),
                  text=(visit, depart),
                  man=(visit, depart))
-    app.add_directive('refcounting', refcounting_directive, 0, (1, 0, 0))
+    app.add_directive('refcounting', refcounting_directive)

doc/upgrading.rst

@@ -47,13 +47,13 @@ List of Incompatible Changes
 
 **Underlying type of JSON integers**
     The underlying C type of JSON integers has been changed from
-    :type:`int` to the widest available signed integer type, i.e.
-    :type:`long long` or :type:`long`, depending on whether
-    :type:`long long` is supported on your system or not. This makes
+    ``int`` to the widest available signed integer type, i.e.
+    ``long long`` or ``long``, depending on whether
+    ``long long`` is supported on your system or not. This makes
     the whole 64-bit integer range available on most modern systems.
 
     ``jansson.h`` has a typedef :type:`json_int_t` to the underlying
-    integer type. :type:`int` should still be used in most cases when
+    integer type. ``int`` should still be used in most cases when
     dealing with smallish JSON integers, as the compiler handles
     implicit type coercion. Only when the full 64-bit range is needed,
     :type:`json_int_t` should be explicitly used.
@@ -69,8 +69,8 @@ List of Incompatible Changes
 
 **Unsigned integers in API functions**
     Version 2.0 unifies unsigned integer usage in the API. All uses of
-    :type:`unsigned int` and :type:`unsigned long` have been replaced
-    with :type:`size_t`. This includes flags, container sizes, etc.
+    ``unsigned int`` and ``unsigned long`` have been replaced
+    with ``size_t``. This includes flags, container sizes, etc.
     This should not require source code changes, as both
-    :type:`unsigned int` and :type:`unsigned long` are usually
-    compatible with :type:`size_t`.
+    ``unsigned int`` and ``unsigned long`` are usually
+    compatible with ``size_t``.