From b4dca6e24ca2aa8dbfdd3cb385c23fce592a85c0 Mon Sep 17 00:00:00 2001 From: David Lord Date: Fri, 5 Aug 2022 11:02:12 -0700 Subject: [PATCH] merge foreword into design --- docs/design.rst | 25 +++++++++++++++++++++- docs/foreword.rst | 53 ----------------------------------------------- docs/index.rst | 10 ++++----- 3 files changed, 28 insertions(+), 60 deletions(-) delete mode 100644 docs/foreword.rst diff --git a/docs/design.rst b/docs/design.rst index a5ef2568..066cf107 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -130,9 +130,25 @@ being present. You can easily use your own templating language, but an extension could still depend on Jinja itself. -Micro with Dependencies +What does "micro" mean? ----------------------- +“Micro” does not mean that your whole web application has to fit into a single +Python file (although it certainly can), nor does it mean that Flask is lacking +in functionality. The "micro" in microframework means Flask aims to keep the +core simple but extensible. Flask won't make many decisions for you, such as +what database to use. Those decisions that it does make, such as what +templating engine to use, are easy to change. Everything else is up to you, so +that Flask can be everything you need and nothing you don't. + +By default, Flask does not include a database abstraction layer, form +validation or anything else where different libraries already exist that can +handle that. Instead, Flask supports extensions to add such functionality to +your application as if it was implemented in Flask itself. Numerous extensions +provide database integration, form validation, upload handling, various open +authentication technologies, and more. Flask may be "micro", but it's ready for +production use on a variety of needs. + Why does Flask call itself a microframework and yet it depends on two libraries (namely Werkzeug and Jinja2). Why shouldn't it? If we look over to the Ruby side of web development there we have a protocol very @@ -201,5 +217,12 @@ requirements and Flask could not meet those if it would force any of this into the core. The majority of web applications will need a template engine in some sort. However not every application needs a SQL database. +As your codebase grows, you are free to make the design decisions appropriate +for your project. Flask will continue to provide a very simple glue layer to +the best that Python has to offer. You can implement advanced patterns in +SQLAlchemy or another database tool, introduce non-relational data persistence +as appropriate, and take advantage of framework-agnostic tools built for WSGI, +the Python web interface. + The idea of Flask is to build a good foundation for all applications. Everything else is up to you or extensions. diff --git a/docs/foreword.rst b/docs/foreword.rst deleted file mode 100644 index 28b272d7..00000000 --- a/docs/foreword.rst +++ /dev/null @@ -1,53 +0,0 @@ -Foreword -======== - -Read this before you get started with Flask. This hopefully answers some -questions about the purpose and goals of the project, and when you -should or should not be using it. - -What does "micro" mean? ------------------------ - -“Micro” does not mean that your whole web application has to fit into a single -Python file (although it certainly can), nor does it mean that Flask is lacking -in functionality. The "micro" in microframework means Flask aims to keep the -core simple but extensible. Flask won't make many decisions for you, such as -what database to use. Those decisions that it does make, such as what -templating engine to use, are easy to change. Everything else is up to you, so -that Flask can be everything you need and nothing you don't. - -By default, Flask does not include a database abstraction layer, form -validation or anything else where different libraries already exist that can -handle that. Instead, Flask supports extensions to add such functionality to -your application as if it was implemented in Flask itself. Numerous extensions -provide database integration, form validation, upload handling, various open -authentication technologies, and more. Flask may be "micro", but it's ready for -production use on a variety of needs. - -Configuration and Conventions ------------------------------ - -Flask has many configuration values, with sensible defaults, and a few -conventions when getting started. By convention, templates and static -files are stored in subdirectories within the application's Python -source tree, with the names :file:`templates` and :file:`static` -respectively. While this can be changed, you usually don't have to, -especially when getting started. - -Growing with Flask ------------------- - -Once you have Flask up and running, you'll find a variety of extensions -available in the community to integrate your project for production. - -As your codebase grows, you are free to make the design decisions appropriate -for your project. Flask will continue to provide a very simple glue layer to -the best that Python has to offer. You can implement advanced patterns in -SQLAlchemy or another database tool, introduce non-relational data persistence -as appropriate, and take advantage of framework-agnostic tools built for WSGI, -the Python web interface. - -Flask includes many hooks to customize its behavior. Should you need -more customization, the Flask class is built for subclassing. If you are -curious about the Flask design principles, head over to the section -about :doc:`design`. diff --git a/docs/index.rst b/docs/index.rst index 5bc787ef..d34feb59 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,14 +29,14 @@ toolkit. The documentation for these libraries can be found at: User's Guide ------------ -This part of the documentation, which is mostly prose, begins with some -background information about Flask, then focuses on step-by-step -instructions for web development with Flask. +Flask provides configuration and conventions, with sensible defaults, to get started. +This section of the documentation explains the different parts of the Flask framework +and how they can be used, customized, and extended. Beyond Flask itself, look for +community-maintained extensions to add even more functionality. .. toctree:: :maxdepth: 2 - foreword installation quickstart tutorial/index @@ -75,8 +75,6 @@ method, this part of the documentation is for you. Additional Notes ---------------- -Design notes, legal information and changelog are here for the interested. - .. toctree:: :maxdepth: 2