falcon icon indicating copy to clipboard operation
falcon copied to clipboard

Published 20 hours ago • verified publisher icon falconry

[Umbrella] Better Docs!

Open kgriffs opened this issue 6 years ago • 7 comments

  • More Tutorials/Guides/Recipes
    • Integration guide for SQLAlchemy, perhaps also marshmallow?
      • https://github.com/wileykestner/falcon-sqlalchemy-demo
      • https://gitlab.com/skosh/falcon-helpers/blob/master/falcon_helpers/sqla/db.py
      • https://gitlab.com/skosh/falcon-helpers/blob/master/falcon_helpers/middlewares/sqla.py
      • https://github.com/vytas7/falcon-sqla :arrow_left: could be moved under the Falconry umbrella once docs have been improved
    • Integration guide for 2-3 popular configuration frameworks
    • Integration guide for templating libraries?
    • Lifecycle management
      • implementing close() when assigning to resp.stream
    • Logging: logging requests/responses, error logging, contextual logging of other information
    • ~~ASGI tutorial to highlight features~~ Done! https://falcon.readthedocs.io/en/latest/user/tutorial-asgi.html
  • Fast prototyping / evaluation
    • Read-made docker containers, orchestration templates, and/or cloud images
    • Recipes (combine with above idea for containers/templates, and/or command-line skeleton app generator
  • Additional Deployment guides / production concerns (e.g., integration with prometheus)
    • https://github.com/jmvrbanac/falcon-example
  • Best practices summary for best performance
    • (Some of these may also go in the deployment guides)
    • PyPy
    • Using an alternative JSON library, or even MessagePack
  • Better description of benchmarks (and better benchmarks to begin with)
  • Tutorial or guide for how to write Cython in your app to use with Falcon
  • Guide to using CFFI for native extensions in C/Rust
  • What else?

kgriffs avatar Dec 21 '18 19:12 kgriffs

Maybe ready-made Docker containers, orchestration templates, cloud images, VM appliances to allow people evaluating / prototyping even quicker?

Where the said ready-made containers would illustrate some of the points above.

vytas7 avatar Dec 21 '18 19:12 vytas7

(See also: https://github.com/falconry/falcon/issues/1391)

kgriffs avatar Dec 21 '18 20:12 kgriffs

Maybe ready-made Docker containers, orchestration templates, cloud images, VM appliances to allow people evaluating / prototyping even quicker?

Thanks! Added to the list.

kgriffs avatar Jan 04 '19 17:01 kgriffs

@kgriffs I have been using Falcon at work in Production and love it! I was currently working on a library and stumbled upon the Issues page, and eventually here. Please let me know how I can contribute. Since the list is large, should we go ahead and start taski-fying these?

bhargavrpatel avatar Feb 05 '19 19:02 bhargavrpatel

@bhargavrpatel Welcome! For now we are still brainstorming a bit while we finalize the 2.0 release and wait for development to open on the 3.0 branch. That being said, I think we can start breaking down these ideas into issues soon and sussing out what should go in 3.0 vs. 3.1.

kgriffs avatar Mar 08 '19 22:03 kgriffs

As mentioned by @amitvadhel on Gitter, another popular way to quickstart development that people turn to is Cookiecutter [1].

There is a Falcon recipe to it [2], but it is fairly outdated, we could consider submitting a new one (idea falls under Fast prototyping).

  1. https://github.com/audreyr/cookiecutter
  2. https://github.com/dgarana/cookiecutter-falcon

vytas7 avatar Apr 19 '19 19:04 vytas7

Someone made a new cookiecutter for Falcon 3.x: https://github.com/pozetroninc/cookiecutter-falcon3

vytas7 avatar Oct 14 '21 12:10 vytas7