Further adjustments to Ligare.web guides.

sphinx-docs/source/cookbook/web_applications/create-application-from-scratch/2-creating-the-application.rst

@@ -64,67 +64,55 @@ Modify ``app/__init__.py`` with the following.
    result.run()
 
 
-Now we have something we can run - but it doesn't do a whole lot. Go ahead and run this code.
+Now we have something we can run. Go ahead and run this code.
 
 .. code-block:: shell-session
 
    user@: my-ligare-app $ python app/__init__.py
 
-As you can see, nothing really happens. This is because a builder needs to `build` what it has configured, and then something needs to be done with the built object.
+Unfortunately, it seems we have another step to take because the application tells us it cannot find its configuration file.
+That makes sense, because we haven't created it yet.
 
-Add this to the end of ``app/__init__.py``.
+.. code-block:: console
 
-.. code-block:: python
-
-   result = application_builder.build()
-
-Now if we run the application, we get this error.
-
-   InvalidBuilderStateError: Cannot build the application config without either `use_ssm` or `use_filename` having been configured.
+   ConfigInvalidError: The configuration file specified, `app/config.toml`,
+   could not be found at `/my-ligare-app/app/config.toml` and was not loaded.
+   Is the file path correct?
 
-We're getting there, but this error tells us that we still need to modify the builder to satisfy a requirement.
-In this case, we need to add the method ``use_configuration``, and we need to add a config file.
-
-Change ``app/__init__.py`` to look like this.
-
-.. code-block:: python
-
-   application_builder = ApplicationBuilder[FlaskApp]() \
-      .use_configuration(
-         lambda config_builder: \
-            config_builder.with_config_filename("app/config.toml")
-      )
-
-   result = application_builder.build()
-
-And create the config file.
+Let's create that file.
 
 .. code-block:: shell-session
 
-   user@: my-ligare-app $ touch app/config.toml
+   user@: my-ligare-app $ cat > app/config.toml <<EOF
+   [logging]
+   format = 'plaintext'
 
-Now if we run the application, we still get an error, but we're told that the config file is invalid.
+   [flask]
+   app_name = 'app'
+   EOF
 
-   Exception: You must set [flask] in the application configuration
+.. note::
 
-This is because we didn't actually put anything in the config file. So let's do that.
+   Due to a `bug <https://github.com/uclahs-cds/Ligare/issues/158>`_ with JSON logging, plaintext logging must be configured.
+   This format also makes it easier to read the output of your application in the console when you are building and testing it.
 
-Change ``app/config.toml`` to the following.
+Run the application again.
 
-.. code-block:: toml
+.. code-block:: shell-session
 
-   [flask]
-   app_name = 'app'
+   user@: my-ligare-app $ python app/__init__.py
 
-Now if we run the application, we get a single line of output and the application exits.
-Add one more line to ``app/__init__.py``. This tells the application to start accepting
-API requests so that it doesn't just immediately exit.
+Now you will see this.
 
-.. code-block:: python
+.. code-block:: console
 
-   result.app_injector.app.run()
+   * Serving Flask app 'app'
+   * Debug mode: off
+   WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
+   * Running on http://localhost:5000
+   Press CTRL+C to quit
 
-Now you can visit http://localhost:5000 to see your application in action!
+Congrats! Your application is running. Now you can visit http://localhost:5000 to see your application in action!
 
 But it doesn't do anything except tell you that nothing can be found.
 

sphinx-docs/source/cookbook/web_applications/create-application-from-scratch/3-adding-api-endpoints.rst

@@ -16,7 +16,9 @@ The specification is an `OpenAPI specification <https://swagger.io/specification
 Modifying the Existing Application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-First, let's modify the application config file ``app/config.toml``. Add the ``flask.openapi`` section so your file looks like this.
+We need to have your application load the OpenAPI specification file, which is used to control the details of your API.
+
+Let's modify the application config file ``app/config.toml`` to add the ``flask.openapi`` section.
 
 .. code-block:: shell-session
 
@@ -26,50 +28,19 @@ First, let's modify the application config file ``app/config.toml``. Add the ``f
 
    EOF
 
-This change allows us to use an OpenAPI specification file to control details of the API endpoint.
-
-
-.. note::
-
-   Due to a `bug <https://github.com/uclahs-cds/Ligare/issues/158>`_ with JSON logging, plaintext logging must be configured.
-
-   .. code-block:: shell-session
-
-      user@: my-ligare-app $ cat >> app/config.toml << EOF
-      [logging]
-      format = 'plaintext'
-
-      EOF
-
 Your file will look like this.
 
 .. code-block:: toml
 
+   [logging]
+   format = 'plaintext'
+
    [flask]
    app_name = 'app'
 
    [flask.openapi]
    spec_path = 'openapi.yaml'
 
-   [logging]
-   format = 'plaintext'
-
-Finally, let's make a few modifications to ``app/__init__.py``.
-This ensures the ``localhost`` and ``port`` options in ``config.toml`` are used.
-
-.. code-block:: python
-
-   from Ligare.web.config import FlaskConfig
-
-   application_builder = ApplicationBuilder[FlaskApp]() \
-      .use_configuration(
-         lambda config_builder: \
-            config_builder.with_config_filename("app/config.toml")
-      )
-
-   result = application_builder.build()
-   result.run()
-
 Adding Endpoints
 ^^^^^^^^^^^^^^^^
 

sphinx-docs/source/cookbook/web_applications/create-application-from-scratch/4-additional-features.rst

@@ -8,6 +8,9 @@ Additional Features
 Swagger UI
 ^^^^^^^^^^
 
-``Ligare.web`` ships with `Swagger UI <https://swagger.io/tools/swagger-ui/>`_, which makes testing your API simple.
+``Ligare.web`` ships with `Swagger UI <https://swagger.io/tools/swagger-ui/>`_, which makes manually testing your API simple.
 
-When your application is running you can access Swagger UI at http://localhost:5000/ui by default.
+By default, the URL ``/ui`` is reserved so you can access this tool at http://localhost:5000/ui when your application is running.
+
+The Swagger UI URL takes precendence over any specified in your openapi.yaml file; that is, if you use ``/ui`` in your OpenAPI specification,
+it will be ignored.