docs(media): add an example for using a custom JSON encoder

[maxking]

Summary of Changes

Adds an example on how to override the default json encoder used by Falcon.

Pull Request Checklist

This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

• Applied changes to both WSGI and ASGI code paths and interfaces (where applicable).
• Added tests for changed code.
• Prefixed code comments with GitHub nick and an appropriate prefix.
• Coding style is consistent with the rest of the framework.
• Updated documentation for changed code.
  • Added docstrings for any new classes, functions, or modules.
  • Updated docstrings for any modifications to existing code.
  • Updated both WSGI and ASGI docs (where applicable).
  • Added references to new classes, functions, or modules to the relevant RST file under docs/.
  • Updated all relevant supporting documentation files under docs/.
  • A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
  • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
• Changes (and possible deprecations) have towncrier news fragments under docs/_newsfragments/, with the file name format {issue_number}.{fragment_type}.rst. (Run towncrier --draft to ensure it renders correctly.)

[codecov]

Codecov Report

Merging #2035 (d5418c0) into master (43a8e80) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##            master     #2035   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           63        63           
  Lines         6707      6707           
  Branches      1238      1238           
=========================================
  Hits          6707      6707           

Impacted Files	Coverage Δ
falcon/media/json.py	100.00% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 43a8e80...d5418c0. Read the comment docs.

[vytas7]

Thanks for this improvement to our docs @maxking!

This is not critical to pass review, but while at it, could you also link to the new paragraph from this FAQ answer: How can I use resp.media with types like datetime?

[maxking]

Working on adding a reference back from FAQ, Sphinx doesn't seem to like sections inside the docstrings and I am trying to see how to create a reference without a section in a paragraph. Will update the PR as soon as I can figure that out. :D

[vytas7]

This LGTM bar one typo.

And wrt linking to a target inside a docstring, it is apparently possible using some kind of marker that isn't a section (as sections are disallowed inside docstring), for instance, a rubric.

The following seems to work, but it adds visible rubrics that we don't use much elsewhere, so probably not worth the effort:

diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index 9d3f09d..60c104f 100644
--- a/docs/user/faq.rst
+++ b/docs/user/faq.rst
@@ -1239,3 +1239,8 @@ Alternatively, you can set the Cookie header directly as demonstrated in this ve
 To include multiple values, simply use ``"; "`` to separate each name-value
 pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``,
 you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``.
+
+How do I link to a rubric inside a docstring
+--------------------------------------------
+
+Trying... :ref:`target_to_paragraph`
diff --git a/falcon/media/json.py b/falcon/media/json.py
index e6cb0cf..a0359ae 100644
--- a/falcon/media/json.py
+++ b/falcon/media/json.py
@@ -179,6 +179,10 @@ class JSONHandlerWS(TextBaseHandlerWS):
         app = falcon.asgi.App()
         app.ws_options.media_handlers[falcon.WebSocketPayloadType.TEXT] = json_handler
 
+    .. _target_to_paragraph:
+
+    .. rubric:: About ensure_ascii
+
     By default, ``ensure_ascii`` is passed to the ``json.dumps`` function.
     If you override the ``dumps`` function, you will need to explicitly set
     ``ensure_ascii`` to ``False`` in order to enable the serialization of

[maxking]

Thanks @vytas7, updated the PR.

[vytas7]

LGTM 👍
(I've taken the liberty of tweaking those rubrics a bit to my liking.)

Thanks for this improvement to our docs, @maxking!