docs(tutorial): port the ASGI tutorial (#1737)

* docs(tutorial): start porting the ASGI tutorial (work-in-progress) * chore(tools): fix a PEP8 import order violation in check_copy_paste.py * docs(tutorial): make further progress porting the ASGI tutorial * docs(ASGI tutorial): copy-paste the testing part WiP: replace `birdisle` (it is getting stale/abandoned wrt new CPython versions) w/ smth else. Add "copy-paste under" directives `for setup.py` and `tox.ini`. * WiP: port tests and set up running them in our CI * WiP: kindly ask Git not to ignore asgilook coverage config * Move Redis configuration to a more fitting place in the text. * docs(asgilook): swap out the sadly unmaintained `birdisle` to `fakeredis` * docs(asgilook): rework the storage path fixture injection * docs(tutorial): get ready for review... * docs(ASGI tutorial): address a portion of review comments * docs(asgilook): embrace pathlib.Path as per review suggestion * test(asgilook): assert that thumbnails are not corrupted by caching * docs(tutorial): address a batch of kgriffs' comments * docs(tutorial): write a couple of paragraphs on field converters * docs(tutorial): add a paragraph on 404 & 405 * docs(tutorial): misc improvements * docs(ASGI tutorial): clean up and flesh out the testing section * docs(ASGI tutorial): clarify the possibility of matching a sink prefix
falconry · Dec 22, 2020 · 9205f9c · 9205f9c
1 parent ba78a52
commit 9205f9c
Show file tree

Hide file tree

Showing 22 changed files with 1,386 additions and 5 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -34,6 +34,7 @@ jobs:
           - "docs"
           - "towncrier"
           - "look"
+          - "asgilook"
           - "check_vendored"
           - "twine_check"
           - "daphne"

diff --git a/.gitignore b/.gitignore
@@ -36,6 +36,9 @@ pip-log.txt
 htmlcov
 nosetests.xml
 
+# ASGI tutorial
+!examples/asgilook/.coveragerc
+
 # Docs
 docs/_build
 dash

diff --git a/docs/api/routing.rst b/docs/api/routing.rst
@@ -261,6 +261,8 @@ specifications in the URI template:
         some_resource
     )
 
+.. _routing_builtin_converters:
+
 Built-in Converters
 -------------------
 
@@ -283,6 +285,8 @@ Built-in Converters
 .. autoclass:: falcon.routing.DateTimeConverter
     :members:
 
+.. _routing_custom_converters:
+
 Custom Converters
 -----------------
 

diff --git a/docs/user/faq.rst b/docs/user/faq.rst
@@ -258,6 +258,8 @@ same resource class:
     app.add_route('/resources/{id}', resource)
     app.add_route('/resources', resource, suffix='collection')
 
+.. _recommended-route-layout:
+
 What is the recommended way to map related routes to resource classes?
 ----------------------------------------------------------------------
 
@@ -904,6 +906,8 @@ Furthermore, the HTTP2 standard also mandates that header field names MUST be
 converted to lowercase (see `RFC 7540, Section 8.1.2
 <https://httpwg.org/specs/rfc7540.html#rfc.section.8.1.2>`_).
 
+.. _faq_static_files:
+
 Can Falcon serve static files?
 ------------------------------
 
@@ -967,6 +971,8 @@ use cases that may not be supported by your client library, simply encapsulate
 the client library within a management class that handles all the tricky bits,
 and pass that around instead.
 
+.. _configuration-approaches:
+
 What is the recommended approach for making configuration variables available to multiple resource classes?
 -----------------------------------------------------------------------------------------------------------
 

diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -8,5 +8,6 @@ User Guide
    install
    quickstart
    tutorial
+   tutorial-asgi
    recipes/index
    faq