Use first admonition line

nineteendo · Sep 17, 2024 · 0b0063e · 0b0063e
1 parent 4834dc7
commit 0b0063e
Show file tree

Hide file tree

Showing 9 changed files with 48 additions and 86 deletions.
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -4,9 +4,7 @@ Changelog
 jsonyx 2.0.0 (unreleased)
 -------------------------
 
-.. todo::
-
- Add release date
+.. todo:: Add release date
 
 - Added the ``jsonyx`` command line utility
 - Added *commas*, *indent_leaves*, *mapping_types*, *seq_types* and

diff --git a/docs/source/get-started.rst b/docs/source/get-started.rst
@@ -40,9 +40,7 @@ To use :mod:`jsonyx`, first install it using pip,
 
  .. rubric:: pipx (PyPI)
 
- .. todo::
-
- Add command
+ .. todo:: Add command
 
  .. tab:: GitHub
 
@@ -197,9 +195,8 @@ Compact encoding
  >>> encoder.dumps({"a": 1, "b": 2, "c": 3})
  '{"a":1,"b":2,"c":3}'
 
-.. tip::
- Use ``quoted_keys=False`` for even more compact encoding, but this isn't
- widely supported.
+.. tip:: Use ``quoted_keys=False`` for even more compact encoding, but this
+ isn't widely supported.
 
 Pretty printing
 ^^^^^^^^^^^^^^^
@@ -232,14 +229,12 @@ Pretty printing
  "bar": {"a": 1, "b": 2, "c": 3}
  }
 
-.. tip::
- Use ``ensure_ascii=True`` to escape non-ASCII characters,
+.. tip:: Use ``ensure_ascii=True`` to escape non-ASCII characters,
  ``indent_leaves=True`` to indent everything and ``sort_keys=True`` to sort
  the keys of objects.
 
-.. seealso::
- The built-in :mod:`pprint` module for pretty-printing arbitrary Python data
- structures.
+.. seealso:: The built-in :mod:`pprint` module for pretty-printing arbitrary
+ Python data structures.
 
 Decoding JSON
 ^^^^^^^^^^^^^
@@ -319,9 +314,8 @@ Using :class:`decimal.Decimal` instead of :class:`float`
  >>> decoder.loads("[1.0000000000000001, 1e400]")
  [Decimal('1.0000000000000001'), Decimal('1E+400')]
 
-.. note::
- :class:`decimal.Decimal` can be natively serialized, but not as fast as
- :class:`float`.
+.. note:: :class:`decimal.Decimal` can be natively serialized, but not as fast
+ as :class:`float`.
 
 Making a patch from two Python objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -359,8 +353,7 @@ Applying a patch
  >>> manipulator.apply_patch([1, 2, 3], {'op': 'del', 'path': '$[1]'})
  [1, 3]
 
-.. tip::
- Using queries instead of indices is more robust.
+.. tip:: Using queries instead of indices is more robust.
 
 Using the ``jsonyx`` command line utility
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/how-to.rst b/docs/source/how-to.rst
@@ -18,8 +18,7 @@ Traceback (most recent call last):
  ^
 jsonyx.JSONSyntaxError: Expecting value
 
-.. seealso::
- :func:`jsonyx.format_syntax_error` for formatting the exception.
+.. seealso:: :func:`jsonyx.format_syntax_error` for formatting the exception.
 
 Specializing JSON object encoding
 ---------------------------------

diff --git a/src/jsonyx/__init__.py b/src/jsonyx/__init__.py
@@ -102,9 +102,8 @@ def format_syntax_error(exc: JSONSyntaxError) -> list[str]:
  ^
  jsonyx.JSONSyntaxError: Expecting value
 
- .. note::
- Don't use :func:`traceback.format_exception_only`, it displays less
- information.
+ .. note:: Don't use :func:`traceback.format_exception_only`, it displays
+ less information.
  """
  if exc.end_lineno == exc.lineno:
  line_range: str = f"{exc.lineno:d}"
@@ -198,8 +197,7 @@ def loads(
  >>> json.loads('{"foo": ["bar", null, 1.0, 2]}')
  {'foo': ['bar', None, 1.0, 2]}
 
- .. tip::
- Specify *filename* to display the filename in error messages.
+ .. tip:: Specify *filename* to display the filename in error messages.
  """
  return Decoder(allow=allow, use_decimal=use_decimal).loads(
  s, filename=filename,
@@ -254,12 +252,10 @@ def write(
  ...
  '["filesystem API"]\n'
 
- .. note::
- The item separator is automatically stripped when indented.
+ .. note:: The item separator is automatically stripped when indented.
 
- .. warning::
- Avoid specifying ABCs for *mapping_types* or *seq_types*, that is very
- slow.
+ .. warning:: Avoid specifying ABCs for *mapping_types* or *seq_types*, that
+ is very slow.
 
  .. versionchanged:: 2.0
  Added *commas*, *indent_leaves*, *mapping_types*, *seq_types* and
@@ -329,12 +325,10 @@ def dump(
  >>> io.getvalue()
  '["streaming API"]\n'
 
- .. note::
- The item separator is automatically stripped when indented.
+ .. note:: The item separator is automatically stripped when indented.
 
- .. warning::
- Avoid specifying ABCs for *mapping_types* or *seq_types*, that is very
- slow.
+ .. warning:: Avoid specifying ABCs for *mapping_types* or *seq_types*, that
+ is very slow.
 
  .. versionchanged:: 2.0
  Added *commas*, *indent_leaves*, *mapping_types*, *seq_types* and
@@ -398,12 +392,10 @@ def dumps(
  >>> json.dumps(["foo", {"bar": ("baz", None, 1.0, 2)}])
  '["foo", {"bar": ["baz", null, 1.0, 2]}]\n'
 
- .. note::
- The item separator is automatically stripped when indented.
+ .. note:: The item separator is automatically stripped when indented.
 
- .. warning::
- Avoid specifying ABCs for *mapping_types* or *seq_types*, that is very
- slow.
+ .. warning:: Avoid specifying ABCs for *mapping_types* or *seq_types*, that
+ is very slow.
 
  .. versionchanged:: 2.0
  Added *commas*, *indent_leaves*, *mapping_types*, *seq_types* and
@@ -449,11 +441,9 @@ def apply_patch(
  >>> json.apply_patch([1, 2, 3], {'op': 'del', 'path': '$[1]'})
  [1, 3]
 
- .. tip::
- Using queries instead of indices is more robust.
+ .. tip:: Using queries instead of indices is more robust.
 
- .. todo::
- Update raised exceptions.
+ .. todo:: Update raised exceptions.
 
  .. versionadded:: 2.0
  """
@@ -494,11 +484,9 @@ def run_select_query(
  >>> root[0]
  [1, 2, 3, None, None, None]
 
- .. tip::
- Using queries instead of indices is more robust.
+ .. tip:: Using queries instead of indices is more robust.
 
- .. todo::
- Update raised exceptions.
+ .. todo:: Update raised exceptions.
 
  .. versionadded:: 2.0
  """
@@ -531,8 +519,7 @@ def run_filter_query(
  >>> node = [None], 0
  >>> assert json.run_filter_query(node, "@ == null")
 
- .. todo::
- Update raised exceptions.
+ .. todo:: Update raised exceptions.
 
  .. versionadded:: 2.0
  """

diff --git a/src/jsonyx/_decoder.py b/src/jsonyx/_decoder.py
@@ -134,13 +134,11 @@ class DuplicateKey(str):
  >>> {json.DuplicateKey('key'): 'value 1', json.DuplicateKey('key'): 'value 2'}
  {'key': 'value 1', 'key': 'value 2'}
 
- .. tip::
- To retrieve the value of a duplicate key, you can
+ .. tip:: To retrieve the value of a duplicate key, you can
  :ref:`use a multi dict <use_multidict>`.
 
- .. seealso::
- :data:`jsonyx.allow.DUPLICATE_KEYS` for loading a dictionary with
- duplicate keys.
+ .. seealso:: :data:`jsonyx.allow.DUPLICATE_KEYS` for loading a
+ dictionary with duplicate keys.
  """
 
  __slots__: tuple[()] = ()
@@ -170,8 +168,8 @@ class JSONSyntaxError(SyntaxError):
  ^
  jsonyx.JSONSyntaxError: Expecting value
 
- .. seealso::
- :func:`jsonyx.format_syntax_error` for formatting the exception.
+ .. seealso:: :func:`jsonyx.format_syntax_error` for formatting the
+ exception.
  """
 
  def __init__(
@@ -242,8 +240,7 @@ def detect_encoding(b: bytearray | bytes) -> str:
  >>> b.decode(json.detect_encoding(b))
  '"foo"'
 
- .. note::
- Supports only ``"utf_8"``, ``"utf_8-sig"``, ``"utf_16"``,
+ .. note:: Supports only ``"utf_8"``, ``"utf_8-sig"``, ``"utf_16"``,
  ``"utf_16_be"``, ``"utf_16_le"``, ``"utf_32"``, ``"utf_32_be"`` and
  ``"utf_32_le"``.
  """
@@ -706,8 +703,7 @@ def loads(
  >>> decoder.loads('{"foo": ["bar", null, 1.0, 2]}')
  {'foo': ['bar', None, 1.0, 2]}
 
- .. tip::
- Specify *filename* to display the filename in error messages.
+ .. tip:: Specify *filename* to display the filename in error messages.
  """
  filename = fspath(filename)
  if not filename.startswith("<") and not filename.endswith(">"):

diff --git a/src/jsonyx/_encoder.py b/src/jsonyx/_encoder.py
@@ -282,12 +282,10 @@ class Encoder:
  :param sort_keys: sort the keys of objects
  :param trailing_comma: add a trailing comma when indented
 
- .. note::
- The item separator is automatically stripped when indented.
+ .. note:: The item separator is automatically stripped when indented.
 
- .. warning::
- Avoid specifying ABCs for *mapping_types* or *seq_types*, that is very
- slow.
+ .. warning:: Avoid specifying ABCs for *mapping_types* or *seq_types*, that
+ is very slow.
 
  .. versionchanged:: 2.0
  Added *commas*, *indent_leaves*, *mapping_types*, *seq_types* and

diff --git a/src/jsonyx/_manipulator.py b/src/jsonyx/_manipulator.py
@@ -622,11 +622,9 @@ def apply_patch(
  >>> manipulator.apply_patch([1, 2, 3], {'op': 'del', 'path': '$[1]'})
  [1, 3]
 
- .. tip::
- Using queries instead of indices is more robust.
+ .. tip:: Using queries instead of indices is more robust.
 
- .. todo::
- Update raised exceptions.
+ .. todo:: Update raised exceptions.
  """
  root: list[Any] = [obj]
  if isinstance(patch, dict):
@@ -665,11 +663,9 @@ def run_select_query(
  >>> root[0]
  [1, 2, 3, None, None, None]
 
- .. tip::
- Using queries instead of indices is more robust.
+ .. tip:: Using queries instead of indices is more robust.
 
- .. todo::
- Update raised exceptions.
+ .. todo:: Update raised exceptions.
  """
  if isinstance(nodes, tuple):
  nodes = [nodes]
@@ -703,8 +699,7 @@ def run_filter_query(
  >>> node = [None], 0
  >>> assert manipulator.run_filter_query(node, "@ == null")
 
- .. todo::
- Update raised exceptions.
+ .. todo:: Update raised exceptions.
  """
  if isinstance(nodes, tuple):
  nodes = [nodes]

diff --git a/src/jsonyx/_speedups.c b/src/jsonyx/_speedups.c
@@ -55,12 +55,10 @@ static PyTypeObject PyDuplicateKeyType = {
  ">>> {json.DuplicateKey('key'): 'value 1', json.DuplicateKey('key'): 'value 2'}\n"
  "{'key': 'value 1', 'key': 'value 2'}\n"
  "\n"
- ".. tip::\n"
- " To retrieve the value of a duplicate key, you can\n"
+ ".. tip:: To retrieve the value of a duplicate key, you can\n"
  " :ref:`use a multi dict <use_multidict>`.\n"
  "\n"
- ".. seealso::\n"
- " :data:`jsonyx.allow.DUPLICATE_KEYS` for loading a dictionary with\n"
+ ".. seealso:: :data:`jsonyx.allow.DUPLICATE_KEYS` for loading a dictionary with\n"
  " duplicate keys.\n"
  ),
  .tp_hash = (hashfunc)duplicatekey_hash,

diff --git a/src/jsonyx/allow.py b/src/jsonyx/allow.py
@@ -137,8 +137,7 @@
 #: >>> encoder.dump([nan, inf, -inf])
 #: [NaN, Infinity, -Infinity]
 #:
-#: .. note::
-#: ``Decimal("sNan")`` can't be (de)serialised this way.
+#: .. note:: ``Decimal("sNan")`` can't be (de)serialised this way.
 NAN_AND_INFINITY: frozenset[str] = frozenset({"nan_and_infinity"})
 
 #: Allow unpaired surrogates in strings.
@@ -173,9 +172,8 @@
 #: >>> encoder.dump("\ud800")
 #: "\ud800"
 #:
-#: .. tip::
-#: If you're not using ``read()`` or ``write()``, you still need to set
-#: the unicode error handler to ``"surrogatepass"``.
+#: .. tip:: If you're not using ``read()`` or ``write()``, you still need to
+# set the unicode error handler to ``"surrogatepass"``.
 SURROGATES: frozenset[str] = frozenset({"surrogates"})
 
 #: Allow a trailing comma at the end of arrays and objects.