Merge pull request #47 from ECN/staging

v1.1 RC

docs-src/webqueue2api Package/Configuration.md

@@ -0,0 +1,46 @@
+The configuration of webqueue2api can be managed in two different ways:
+
+- At launch with a configuration file in the same directory as the virtual environment
+- At runtime by modifying the `webqueue2api.config` symbol directly
+
+## Configuration File
+On import, a [ConfigParser INI formatted file](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure) is read for configuartion options. This file must be located in the same directory as the virtual environment folder and must be named `webqueue2api_config.ini`.
+
+!!! example "A Full Config File"
+    ```ini
+    [parser]
+    # Absolute path to directory containing queue data.
+    # Default: /home/pier/e/queue/Mail
+    queue_directory = /etc/queue-cli/queues
+
+    # List of queues to ignore. (Comma and space ", " delimited.)
+    # Default: archives, drafts, inbox, coral
+    queues_to_ignore = dogs, cats, particularly_pugs
+
+    [api]
+    # Runtime configuration for secure production or convenient development settings.
+    # Valid options are: prod | dev
+    # Default: prod
+    environment = dev
+
+    # Token used to encrypt JWT payloads.
+    # Default: webqueue2api.api.config.generate_random_string
+    jwt_secret_key = uV0liG9$YgcGE7J!
+    ```
+
+## Changing Settings at Runtime
+Each package contains package level configuration objects (see: [dataclasses on PyPI](https://pypi.org/project/dataclasses/)) in `config.py` files. All of the configurations are combined into the top level `webqueue2api.config` symbol.
+
+These configuration objects store default values for each package. Default values can be changed by editing these objects directly or by editing the object values before their use.
+
+!!! example "Changing the parser's queue directory by editing object values."
+    ```python
+    import webqueue2api
+
+    # Load Queue from default directory
+    ce_queue = Queue("ce")
+
+    # load Queue from modified directory
+    webqueue2api.config.parser.queue_directory = "/absolute/path"
+    other_queue = Queue("other")
+    ```

docs-src/webqueue2api Package/Getting Started.md

@@ -10,6 +10,31 @@ The webqueue2api Package has the following structure:
 
 ## Basic Usage
 
+!!! example "Load all queues."
+    ```python
+    import webqueue2api
+    all_queues = webqueue2api.load_queues()
+    for queue in all_queues:
+        print(f"{queue.name} has {len(queue.items)} items."
+    ```
+    ```python
+    # Expected Output
+    "tech has 72 items"
+    "ce has 38 items"
+    ...
+    ```
+
+!!! example "Load some queues."
+    ```python
+    import webqueue2api
+    all_queues = webqueue2api.load_queues("che", "tech", "ce")
+    print( len( all_queues ) )
+    ```
+    ```python
+    # Expected Output
+    3
+    ```
+
 !!! example "Load a queue and get the number of items in it."
     ```python
     import webqueue2api

docs-src/webqueue2api Package/Package Structure.md

@@ -5,21 +5,4 @@ The webqueue2api Package consists of four packages in total:
 - `webqueue2api`: The root packages. This contains both the `api` and the `parser` packages as well as global configuration.
     - `api`: Contains a [Flask](https://flask.palletsprojects.com/) app that can be used with any WSGI server to host the webqueue2 API and utilities such as authentication code.
         - `resources`: Contains [Flask-RESTful](https://flask-restful.readthedocs.io/en/latest/) resources for the webqueue2 API.
-    - `parser`: Contains parers for a Queue and an Item as well as utilities and custom errors.
-
-## Configuration
-Each package contains package level configuration objects (see: [dataclasses on PyPI](https://pypi.org/project/dataclasses/)) in `config.py` files. All of the configurations are combined into the top level `webqueue2api.config` symbol.
-
-These configuration objects store default values for each package. Default values can be changed by editing these objects directly or by editing the object values before their use.
-
-!!! example "Changing the parser's queue directory by editing object values."
-    ```python
-    import webqueue2api
-
-    # Load Queue from default directory
-    ce_queue = Queue("ce")
-
-    # load Queue from modified directory
-    webqueue2api.config.parser.queue_directory = "/absolute/path"
-    other_queue = Queue("other")
-    ```
+    - `parser`: Contains parers for a Queue and an Item as well as utilities and custom errors.