Add starting pages for "why" explanations of Ligare libraries.

sphinx-docs/source/libraries/index.rst

@@ -0,0 +1,62 @@
+
+Ligare Libraries
+================
+
+Ligare is a collection of libraries and utilities for creating new applications,
+or extending existing applications.
+
+.. contents::
+   :depth: 2
+   :local:
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
+
+   */index
+
+Why Use Ligare?
+----------------
+
+Here are some use cases for using Ligare in your application,
+or for creating new applications.
+
+For Web Applications
+^^^^^^^^^^^^^^^^^^^^
+
+* You want to create a new web application without worrying about its structure and dependencies
+* You want to write automated tests for web applications
+* You want to extend an existing Flask or Connexion application with Ligare middleware
+
+For Command Line Applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* You need a sophiscated command line application and the utilities to support one, without writing the complexity yourself
+
+For Databases
+^^^^^^^^^^^^^
+
+* You want to use either or both of SQLite and PostgreSQL in your application
+* You want to write automated tests for database usage
+
+For User Authentication and Authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* You need to authenticate users through SSO
+* You need to control authenticated user access to parts of your application
+
+For Advanced Runtime Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* You have configuration requirements that environment variables are insufficient to meet
+* You need to use AWS SSM for secure application configuration
+
+For Sophisicated Application Architecture
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* You want to use dependency injection throughout an application
+* You want to use design patterns that are challenging to implement in Python, like singletons
+
+For Combining All of the Above
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* You need to use a database in a web application
+* You need to control user access in a web application
+* You need a command line application to get a connection string from AWS SSM in order to connect to a database

sphinx-docs/source/libraries/ligare-database/index.rst

@@ -0,0 +1,24 @@
+
+.. _ligare-database:
+
+Ligare.database
+===============
+
+``Ligare.database`` is a library for working with SQLite and PostgreSQL databases.
+It integrates with `SQLAlchemy <https://www.sqlalchemy.org/>`_ as an `ORM <https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping>`_ library,
+and extends `Alembic <https://alembic.sqlalchemy.org/en/latest/>`_ to help `manage your database <https://en.wikipedia.org/wiki/Schema_migration>`_ as it changes over time.
+
+Why Use Ligare.database?
+------------------------
+
+``Ligare.database`` offers:
+
+* SQLite *and* PostgreSQL without having to worry about database-specific behaviors
+
+  * SQLite is often used for tests, while PostgreSQL is used for live applications
+  * As an application grows, moving from SQLite to PostgreSQL is made simpler through ``Ligare.database``
+  * Schemas with SQLite are made possible with ``Ligare.database``
+* Integration with other parts of Ligare, for example, the configuration system, or ``Ligare.web`` web applications
+* The same flexibility as SQLAlchemy with the functionality of Ligare
+* Managed connections so you can set aside the complexity of database connectivity in an application
+

sphinx-docs/source/libraries/ligare-identity/index.rst

@@ -0,0 +1,7 @@
+
+.. _ligare-identity:
+
+Ligare.identity
+===============
+
+``Ligare.identity`` is useful for user access controls.

sphinx-docs/source/libraries/ligare-platform/index.rst

@@ -0,0 +1,26 @@
+
+.. _ligare-platform:
+
+Ligare.platform
+===============
+
+``Ligare.platform`` offers `PaaS <https://en.wikipedia.org/wiki/Platform_as_a_service>`_-like libraries for applications.
+Although currently limited in functionality, it is useful for managing users, and `active functionality <https://martinfowler.com/articles/feature-toggles.html>`_ in an application.
+
+Why Use Ligare.platform?
+------------------------
+
+Managing User Access Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Ligare.platform`` offers a limited form of user management and `RBAC <https://en.wikipedia.org/wiki/Role-based_access_control>`_ within ``ligare.platform.identity``.
+
+This functionality is useful for accessing user information in a database, and controlling a user's access to running code.
+
+Managing Active Functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``ligare.platform.feature_flag`` offers functionality to control whether a given piece of code
+should run. This is useful for controlling things like, e.g., "test" user accounts having access to "beta" functionality while keeping
+"stable" software in place for everyone else. Feature flags are not limited to user access controls, and can be managed by any arbitary
+criteria.

sphinx-docs/source/libraries/ligare-programming/index.rst

@@ -0,0 +1,19 @@
+
+.. _ligare-programming:
+
+Ligare.programming
+==================
+
+``Ligare.programming`` provides functionality to help you extend your application.
+It is a loose collection of programming patterns, utilities, and integration APIs
+for working with other Ligare libraries.
+
+Why Use Ligare.programming?
+---------------------------
+
+``Ligare.programming`` offers several pieces of functionality. You can use it for:
+
+* Extending argparse to allow more sophiscated command line application usage
+* Merging dictionaries and type-hinting nested dictionary types
+* Integrating Ligare's configuration system so your application can avoid hard-coding variables for use during runtime
+* Dependency injection, singletons, and other software design patterns

sphinx-docs/source/libraries/ligare-web/index.rst

@@ -0,0 +1,8 @@
+.. _ligare-web:
+
+Ligare.web
+==========
+
+``Ligare.web`` is a library for creating and extending web applications. It provides all the
+components necessary to create JSON APIs, with optional integration into other
+parts of Ligare.