updated docs with better cmd-line info (#72)

README.md

@@ -16,7 +16,8 @@ applications. `spock` lets you focus on the code you need to write instead of re
 creating ArgParsers, reading configuration files, implementing traceability etc.
 
 In short, `spock` configurations are defined by simple and familiar class-based structures. This allows `spock` to 
-support inheritance, read from multiple markdown formats, and allow hierarchical configuration by composition.
+support inheritance, read from multiple markdown formats, automatically generate cmd-line arguments, and allow 
+hierarchical configuration by composition.
 
 ## Key Features
 

docs/ArgParser-Replacement.md

@@ -0,0 +1,41 @@
+# Drop In Replacement For Argparser
+
+`spock` can easily be used as a drop in for argparser. This means that all parameter definitions as required to come in 
+from the command line or from setting defaults within the `@spock` decorated classes.
+
+### Automatic Command-Line Argument Generation
+
+`spock` will automatically generate command line arguments for each parameter, unless the `no_cmd_line=True` flag is 
+passed to the `ConfigArgBuilder`. Let's create a simple example to demonstrate:
+
+```python
+from spock.config import spock
+from typing import Optional
+
+@spock
+class ExampleConfig:
+    read_path: str = '/tmp'
+    date: int
+    cache_path: Optional[str]
+```
+
+Given these definitions, `spock` will automatically generate a command-line argument (via an internally maintained 
+argparser) for each parameter within each `@spock` decorated class. The syntax follows simple dot notation 
+of `--classname.parameter`. Thus, for our sample classes above, `spock` will automatically generate the following 
+valid command-line arguments:
+
+```shell
+--ExampleConfig.read_path *value*
+--ExampleConfig.date *value*
+--ExampleConfig.cache_path *value*
+```
+
+### Use Spock via the Command-Line
+
+Simply do not pass a `-c` or `--config` argument at the command line and instead pass in all values to the 
+automatically generated cmd-line arguments.
+
+```bash
+$ python simple.py --ExampleConfig.read_path /my/file/path --ExampleConfig.date 1292838124 \
+--ExampleConfig.cache_path /path/to/cache/dir
+```

docs/Motivation.md

@@ -73,25 +73,6 @@ Thus, the idea of of `spock` was born... A simple, understandable, and lightweig
 configurations during Python development. Anyone familiar with Python and knows how to define a basic class object can 
 use `spock` (or if they don't there is plenty of documentation and tutorials on classes).
 
-
-* Simple Declaration: Type checked parameters are defined within a `@spock` decorated class. Supports required/optional 
-and automatic defaults.
-* Easily Managed Parameter Groups: Each class automatically generates its own object within a single namespace.
-* Parameter Inheritance: Classes support inheritance allowing for complex configurations derived from a common base 
-set of parameters.
-* Complex Types: Nested Lists/Tuples, List/Tuples of Enum of `@spock` classes, List of repeated `@spock` classes
-* Multiple Configuration File Types: Configurations are specified from YAML, TOML, or JSON files.
-* Hierarchical Configuration: Compose from multiple configuration files via simple include statements.
-* Command-Line Overrides: Quickly experiment by overriding a value with automatically generated command line arguments.
-* Immutable: All classes are *frozen* preventing any misuse or accidental overwrites.
-* Tractability and Reproducibility: Save runtime parameter configuration to YAML, TOML, or JSON with a single chained 
-  command (with extra runtime info such as Git info, Python version, machine FQDN, etc). The saved markdown file can be
-  used as the configuration input to reproduce prior runtime configurations.
-* Hyper-Parameter Tuner Addon: Provides a unified interface for hyper-parameter tuning that supports various 
-  backends (Optuna, WIP: Ax)
-* S3 Addon: Automatically detects `s3://` URI(s) and handles loading and saving `spock` configuration files when an
-  active `boto3.Session` is passed in (plus any additional `S3Transfer` configurations)
-
 ### Other Libraries
 
 There are other open source complex configuration libraries available for Python. We think that `spock` fits

docs/Quick-Start.md

@@ -1,18 +1,11 @@
 # Quick Start
 
-*Updated for the new and simpler API!*
-
-*New API is 100% backwards compatible with existing code!*
-
 This is a quick and dirty guide to getting up and running with `spock`. Read the 
 [Basic Tutorial](basic_tutorial/About.md) as a simple guide and then explore more
 [Advanced Features](advanced_features/About.md) for in-depth usage.
 
 All examples can be found [here](https://github.com/fidelity/spock/blob/master/examples).
 
-Legacy documentation for the old API (pre v2.0) can be 
-found [here](https://github.com/fidelity/spock/blob/master/docs/legacy)
-
 ### TL;DR
 1. Import the necessary components from `spock`
 2. Create a basic Python class, decorate it with `@spock`
@@ -133,14 +126,7 @@ configuration(s):
     most_fancy_parameter    List[int]    values to apply basic algebra to 
 ```
 
-### Spock As a Drop In For Argparser
+### Spock As a Drop In Replacement For Argparser
 
-`spock` can easily be used as a drop in for argparser. This means that all parameter definitions as required to come in 
-from the command line or from setting defaults within the `@spock` decorated classes. Simply do not pass a `-c` or 
-`--config` argument at the command line and instead pass in all of the automatically generated cmd-line arguments.
-
-
-```bash
-$ python simple.py --BasicConfig.parameter --BasicConfig.fancy_parameter 8.8 --BasicConfig.fancier_parameter 64.64 \
-  --BasicConfig.most_fancy_parameter [768, 768, 512, 128]
-```
+`spock` can easily be used as a drop in replacement for argparser. 
+See the docs/example [here](https://fidelity.github.io/spock/docs/ArgParser-Replacement/).

docs/advanced_features/Command-Line-Overrides.md

@@ -1,11 +1,58 @@
 # Utilizing Command Line Overrides
 
 `spock` supports overriding parameter values set from configuration files via the command line. This can be useful for
-exploration of parameter values or for things like hyperparameter optimization.
+exploration of parameter values, quick-and-dirty value overrides, or to parse other command-line arguments that would
+normally require use of another argparser.
+
+### Automatic Command-Line Argument Generation
+
+`spock` will automatically generate command line arguments for each parameter, unless the `no_cmd_line=True` flag is 
+passed to the `ConfigArgBuilder`. Let's look at two of the `@spock` decorated classes from the `tutorial.py` file to 
+illustrate how this works in practice:
+
+```python
+from enum import Enum
+from spock.args import SavePath
+from spock.config import spock
+from typing import List
+from typing import Optional
+from typing import Tuple
+
+@spock
+class DataConfig:
+    batch_size: int = 2
+    n_samples: int = 8
+    cache_path: Optional[str]
+
+@spock
+class OptimizerConfig:
+    lr: float = 0.01
+    n_epochs: int = 2
+    grad_clip: Optional[float]
+```
+
+Given these definitions, `spock` will automatically generate a command-line argument (via an internally maintained 
+argparser) for each parameter within each `@spock` decorated class. The syntax follows simple dot notation 
+of `--classname.parameter`. Thus, for our sample classes above, `spock` will automatically generate the following 
+valid command-line arguments:
+
+```shell
+--DataConfig.batch_size *value*
+--DataConfig.n_samples *value*
+--DataConfig.cache_path *value*
+--OptimizerConfig.lr *value*
+--OptimizerConfig.n_epochs *value*
+--OptimizerConfig.grad_clip *value*
+```
+
+None of these command-line arguments are required (i.e. sets `required=False` within the argparser), but a value must
+be set via one of the three core mechanisms: (1) a default value (set withing the `@spock` decorated class), (2) the 
+configuration file (passed in with the `--config` argument), or (3) the command-line argument (this takes precedence 
+over all other methods).
 
 ### Overriding Configuration File Values
 
- Let's override a few values from our example in: `tutorial.py`
+Using the automatically generated command-line arguments, let's override a few values from our example in `tutorial.py`:
 
 ```python
 from enum import Enum
@@ -120,14 +167,9 @@ $ python tutorial.py --config tutorial.yaml --TypeConfig.nested_list.NestedListS
 --TypeConfig.nested_list.NestedListStuff.two ['ciao','ciao']
 ```
 
-### Spock As a Drop In For Argparser
+### Spock As a Drop In Replacement For Argparser
 
-`spock` can easily be used as a drop in for argparser. This means that all parameter definitions as required to come in 
-from the command line or from setting defaults within the `@spock` decorated classes. Simply do not pass a `-c` or 
-`--config` argument at the command line and instead pass in all of the automatically generated cmd-line arguments.
-
-
-```bash
-$ python tutorial.py --TypeConfig.nested_list.NestedListStuff.one [1,2] \
-  --TypeConfig.nested_list.NestedListStuff.two [ciao,ciao] ...
-```
+`spock` can easily be used as a drop in replacement for argparser. This means that all parameter definitions as 
+required to come in from the command line or from setting defaults within the `@spock` decorated classes. Simply do not 
+pass a `-c` or`--config` argument at the command line and instead pass in values to all of the automatically generated 
+cmd-line arguments. See more information [here](https://fidelity.github.io/spock/docs/ArgParser-Replacement/).

pyproject.toml

@@ -26,6 +26,9 @@ Motivation = "docs/Motivation.md"
 [[tool.portray.mkdocs.nav]]
 "Quick Start" = "docs/Quick-Start.md"
 
+[[tool.portray.mkdocs.nav]]
+"argparse Replacement" = "docs/ArgParser-Replacement.md"
+
 # Basic Tutorial
 [[tool.portray.mkdocs.nav]]
     [[tool.portray.mkdocs.nav."Basic Tutorial"]]