Documentation

Add cross references between classes and functions. Refill to fit wider margins.

docs/api.rst

@@ -32,29 +32,31 @@
 
    The version of the RapidJSON_ library this module is built with.
 
+
+.. rubric:: `datetime_mode` related constants
+
 .. data:: DM_NONE
 
-   This is the default ``datetime_mode``: *neither* :class:`date` *nor*
-   :class:`datetime` *nor* :class:`time` instances are recognized by
-   :func:`dumps` and :func:`loads`.
+   This is the default `datetime_mode`: *neither* :class:`date` *nor* :class:`datetime`
+   *nor* :class:`time` instances are recognized by :func:`dumps` and :func:`loads`.
 
 .. data:: DM_ISO8601
 
-   In this ``datetime_mode`` mode :func:`dumps` and :func:`loads` handle
-   :class:`date`, :class:`datetime` *and* :class:`date` instances representing
-   those values using the `ISO 8601`_ format.
+   In this `datetime_mode` mode :func:`dumps` and :func:`loads` handle :class:`date`,
+   :class:`datetime` *and* :class:`date` instances representing those values using the
+   `ISO 8601`_ format.
 
 .. data:: DM_UNIX_TIME
 
    This mode tells RapidJSON to serialize :class:`date`, :class:`datetime` and
-   :class:`time` as *numeric timestamps*: for the formers it is exactly the
-   result of their :meth:`timestamp` method, that is as the number of seconds
-   passed since ``EPOCH``; ``date`` instances are serialized as the
-   corresponding ``datetime`` instance with all the `time` slots set to 0;
-   ``time`` instances are serialized as the number of seconds since midnight.
+   :class:`time` as *numeric timestamps*: for the formers it is exactly the result of
+   their :meth:`timestamp` method, that is as the number of seconds passed since
+   ``EPOCH``; ``date`` instances are serialized as the corresponding ``datetime`` instance
+   with all the `time` slots set to 0; ``time`` instances are serialized as the number of
+   seconds since midnight.
 
-   Since this is obviously *irreversible*, this flag is usable **only** for
-   :func:`dumps`: an error is raised when passed to :func:`loads`.
+   Since this is obviously *irreversible*, this flag is usable **only** for :func:`dumps`:
+   an error is raised when passed to :func:`loads`.
 
 .. data:: DM_ONLY_SECONDS
 
@@ -63,74 +65,82 @@
 
 .. data:: DM_IGNORE_TZ
 
-   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`,
-   to ignore the value's timezones.
+   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`, to ignore
+   the value's timezones.
 
 .. data:: DM_NAIVE_IS_UTC
 
-   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`,
-   to tell RapidJSON that the naïve values (that is, without an explicit
-   timezone) are already in UTC_ timezone.
+   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`, to tell
+   RapidJSON that the naïve values (that is, without an explicit timezone) are already in
+   UTC_ timezone.
 
 .. data:: DM_SHIFT_TO_UTC
 
-   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`,
-   to always *shift* values the UTC_ timezone.
+   This can be used combined with :data:`DM_ISO8601` or :data:`DM_UNIX_TIME`, to always
+   *shift* values the UTC_ timezone.
+
+
+.. rubric:: `uuid_mode` related constants
 
 .. data:: UM_NONE
 
-   This is the default ``uuid_mode``: :class:`UUID` instances are *not*
-   recognized by :func:`dumps` and :func:`loads`.
+   This is the default `uuid_mode`: :class:`UUID` instances are *not* recognized by
+   :func:`dumps` and :func:`loads`.
 
 .. data:: UM_CANONICAL
 
-   In this ``uuid_mode``, :func:`loads` recognizes string values containing
-   the ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` canonical representation as
-   :class:`UUID` instances; :func:`dumps` emits same kind of representation
-   for :class:`UUID` instances as a string value.
+   In this `uuid_mode`, :func:`loads` recognizes string values containing the
+   ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` canonical representation as :class:`UUID`
+   instances; :func:`dumps` emits same kind of representation for :class:`UUID` instances
+   as a string value.
 
 .. data:: UM_HEX
 
-   In this ``uuid_mode`` :func:`loads` recognizes string values containing
-   exactly 32 hex digits *or* the ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
-   canonical representation as :class:`UUID` instances; :func:`dumps` emits
-   the 32 hex digits of :class:`UUID` instances as a string value.
+   In this `uuid_mode` :func:`loads` recognizes string values containing exactly 32 hex
+   digits *or* the ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` canonical representation as
+   :class:`UUID` instances; :func:`dumps` emits the 32 hex digits of :class:`UUID`
+   instances as a string value.
+
+
+.. rubric:: `number_mode` related constants
 
 .. data:: NM_NONE
 
-   This is the default ``number_mode``: numeric values can be as wide as the
-   memory allows.
+   This is the default `number_mode`: numeric values can be as wide as the memory allows.
 
 .. data:: NM_DECIMAL
 
-   In this ``number_mode`` :func:`loads` will return floating point values as
-   :class:`Decimal` instances instead of :class:`float`; :func:`dumps` will
-   serialize :class:`Decimal` instances like any other :class:`float` number.
+   In this `number_mode` :func:`loads` will return floating point values as
+   :class:`Decimal` instances instead of :class:`float`; :func:`dumps` will serialize
+   :class:`Decimal` instances like any other :class:`float` number.
 
 .. data:: NM_NAN
 
-   This enables *non-numbers* (i.e. ``nan``, ``+inf`` and ``-inf``) handling
-   in both directions.
+   This enables *non-numbers* (i.e. ``nan``, ``+inf`` and ``-inf``) handling in both
+   directions.
 
 .. data:: NM_NATIVE
 
-   In this alternative ``number_mode`` numeric values must fit into the
-   underlying C library limits, with a considerable speed benefit.
+   In this alternative `number_mode` numeric values must fit into the underlying C library
+   limits, with a considerable speed benefit.
+
+
+.. rubric:: `parse_mode` related constants
 
 .. data:: PM_NONE
 
-   This is the default ``parse_mode``: with the exception of the *NaN and Infinite*
+   This is the default `parse_mode`: with the exception of the *NaN and Infinite*
    recognition active by default, the parser is in *strict mode*.
 
 .. data:: PM_COMMENTS
 
-   In this ``parse_mode``, the parser allows and ignores one-line ``// ...`` and
-   multi-line ``/* ... */`` comments
+   In this `parse_mode`, the parser allows and ignores one-line ``// ...`` and multi-line
+   ``/* ... */`` comments
 
 .. data:: PM_TRAILING_COMMAS
 
-   In this ``parse_mode``, the parser allows and ignores trailing commas at the
-   end of *arrays* and *objects*.
+   In this `parse_mode`, the parser allows and ignores trailing commas at the end of
+   *arrays* and *objects*.
 
 
 .. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601

docs/benchmarks.rst

@@ -9,17 +9,15 @@
  Performance
 =============
 
-``python-rapidjson`` tries to be as performant as possible while staying
-compatible with the ``json`` module.
+``python-rapidjson`` tries to be as performant as possible while staying compatible with
+the ``json`` module.
 
-The following tables show a comparison between this module and other libraries
-with different data sets.  Last row (“overall”) is the total time taken by all
-the benchmarks.
+The following tables show a comparison between this module and other libraries with
+different data sets.  Last row (“overall”) is the total time taken by all the benchmarks.
 
 Each number show the factor between the time taken by each contender and
-``python-rapidjson`` (in other words, they are *normalized* against a value of
-1.0 for ``python-rapidjson``): the lower the number, the speedier the
-contender.
+``python-rapidjson`` (in other words, they are *normalized* against a value of 1.0 for
+``python-rapidjson``): the lower the number, the speedier the contender.
 
 In **bold** the winner.
 
@@ -98,9 +96,9 @@ To run these tests yourself, clone the repo and run:
 
    $ tox -e py36 -- -m benchmark --compare-other-engines
 
-Without the option ``--compare-other-engines`` it will focus only on
-``RapidJSON``.  This is particularly handy coupled with the `compare past
-runs`__ functionality of ``pytest-benchmark``:
+Without the option ``--compare-other-engines`` it will focus only on ``RapidJSON``.  This
+is particularly handy coupled with the `compare past runs`__ functionality of
+``pytest-benchmark``:
 
 .. code-block:: bash
 
@@ -115,9 +113,9 @@ runs`__ functionality of ``pytest-benchmark``:
    test_loads[rapidjson-256 Trues array] (0001)                        5.4180 (1.04)…
    …
 
-To reproduce the tables above, use the option ``--benchmark-json`` so that the
-the results are written in the specified filename the run the
-``benchmark-tables.py`` script giving that filename as the only argument:
+To reproduce the tables above, use the option ``--benchmark-json`` so that the the results
+are written in the specified filename the run the ``benchmark-tables.py`` script giving
+that filename as the only argument:
 
 .. code-block:: bash
 

docs/decoder.rst

@@ -22,17 +22,19 @@
 
    Class-based :func:`loads`\ -like functionality.
 
-   :param int number_mode: enable particular behaviors in handling numbers
-   :param int datetime_mode: how should :class:`datetime` and :class:`date`
-                             instances be handled
-   :param int uuid_mode: how should :class:`UUID` instances be handled
-   :param int parse_mode: whether the parser should allow non-standard JSON extensions
+   :param int number_mode: enable particular :ref:`behaviors in handling numbers
+                           <loads-number-mode>`
+   :param int datetime_mode: how should :ref:`datetime, time and date instances be handled
+                             <loads-datetime-mode>`
+   :param int uuid_mode: how should :ref:`UUID instances be handled <loads-uuid-mode>`
+   :param int parse_mode: whether the parser should allow :ref:`non-standard JSON
+                          extensions <loads-parse-mode>`
 
 
    .. method:: __call__(json)
 
-      :param json: either a ``str`` instance or an *UTF-8* ``bytes`` instance,
-                   containing the ``JSON`` to be decoded
+      :param json: either a ``str`` instance or an *UTF-8* ``bytes`` instance, containing
+                   the ``JSON`` to be decoded
       :returns: a Python value
 
       .. doctest::
@@ -48,8 +50,8 @@
       :param sequence: an instance implement the *mutable sequence* protocol
       :returns: a new value
 
-      This is called, if implemented, when a *JSON array* has been completely
-      parsed, and can be used replace it with an arbitrary different value:
+      This is called, if implemented, when a *JSON array* has been completely parsed, and
+      can be used replace it with an arbitrary different value:
 
       .. doctest::
 
@@ -71,10 +73,9 @@
       :param mapping: an instance implementing the *mapping protocol*
       :returns: a new value
 
-      This is called, if implemented, when a *JSON object* has been completely
-      parsed, and can be used replace it with an arbitrary different value,
-      like what can be done with the ``object_hook`` argument of the
-      :func:`loads` function:
+      This is called, if implemented, when a *JSON object* has been completely parsed, and
+      can be used replace it with an arbitrary different value, like what can be done with
+      the ``object_hook`` argument of the :func:`loads` function:
 
       .. doctest::
 
@@ -100,11 +101,11 @@
 
       :returns: a mapping instance
 
-      This method, when implemented, is called whenever a new *JSON object* is
-      found: it must return an instance implementing the *mapping protocol*.
+      This method, when implemented, is called whenever a new *JSON object* is found: it
+      must return an instance implementing the *mapping protocol*.
 
-      It can be used to select a different implementation than the standard
-      ``dict`` used by default:
+      It can be used to select a different implementation than the standard ``dict`` used
+      by default:
 
       .. doctest::
 
@@ -122,9 +123,8 @@
       :param s: a ``str`` instance
       :returns: a new value
 
-      This method, when implemented, is called whenever a *JSON string* has
-      been completely parsed, and can be used to replace it with an arbitrary
-      different value:
+      This method, when implemented, is called whenever a *JSON string* has been
+      completely parsed, and can be used to replace it with an arbitrary different value:
 
       .. doctest::
 
@@ -136,8 +136,8 @@
          >>> ssc('"Hello World!"')
          'hELLO wORLD!'
 
-      Note that it is called **after** the recognition of dates and UUIDs,
-      when `datetime_mode` and/or `uuid_mode` are specified:
+      Note that it is called **after** the recognition of dates and UUIDs, when
+      `datetime_mode` and/or `uuid_mode` are specified:
 
       .. doctest::