From 7d99308b69a615c6d00180545a492348ae21ff1e Mon Sep 17 00:00:00 2001 From: Nicholas Cilfone Date: Wed, 28 Jul 2021 16:39:45 -0400 Subject: [PATCH] readme reorg --- README.md | 84 ++++++++++++++++++++++++------------------------------- 1 file changed, 36 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 7072d77f..cf6a2fd0 100644 --- a/README.md +++ b/README.md @@ -18,31 +18,50 @@ 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. +## Key Features + +* [Simple Declaration](https://fidelity.github.io/spock/docs/basic_tutorial/Define/): 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](https://fidelity.github.io/spock/docs/advanced_features/Inheritance/): Classes support + inheritance allowing for complex configurations derived from a common base set of parameters. +* [Complex Types](https://fidelity.github.io/spock/docs/advanced_features/Advanced-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](https://fidelity.github.io/spock/docs/advanced_features/Composition/): Compose from + multiple configuration files via simple include statements. +* [Command-Line Overrides](https://fidelity.github.io/spock/docs/advanced_features/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 (to the extent they can be in + Python). +* [Tractability and Reproducibility](https://fidelity.github.io/spock/docs/basic_tutorial/Saving/): 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](https://fidelity.github.io/spock/docs/addons/tuner/About.html): Provides a unified + interface for defining hyper-parameters (via `@spockTuner` decorator) that supports various tuning/algorithm + backends (Optuna, WIP: Ax) +* [S3 Addon](https://fidelity.github.io/spock/docs/addons/S3/): 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) + ## Quick Install Requires Python 3.6+ -```bash -pip install spock-config -``` - -w/ S3 extension +| Base | w/ S3 Extension | w/ Hyper-Parameter Tuner | +|------|-----------------|--------------------------| +| `pip install spock-config` | `pip install spock-config[s3]` | `pip install spock-config[tune]` | -```bash -pip install spock-config[s3] -``` +## Quick Start & Documentation -## Version(s) +Refer to the quick-start guide [here](https://fidelity.github.io/spock/docs/Quick-Start/). -All prior versions are available on PyPi. If legacy API and backend support is needed please install a pre v2.0.0+ -version. We recommend refactoring your code to the new API and backend instead as legacy versions will be missing -recent features, bugfixes, and hotfixes. +Current documentation and more information can be found [here](https://fidelity.github.io/spock/). -* v2.0.0+: Dropped support for legacy backend and API semantics -* v1.1.0-v1.2.1: New API with support for legacy backend and legacy API semantics -* v1.0.0: Legacy API and backend +Example `spock` usage is located [here](https://github.com/fidelity/spock/blob/master/examples). -## News +## News/Releases See [Releases](https://github.com/fidelity/spock/releases) for more information. @@ -60,39 +79,8 @@ active `boto3.Session` * Support for Google docstring style annotation of `spock` class (and Enums) and attributes * Added in ability to print docstring annotated help information to command line with `--help` argument -## Documentation - -Current documentation and more information can be found [here](https://fidelity.github.io/spock/). - -Example `spock` usage is located [here](https://github.com/fidelity/spock/blob/master/examples). - -## Key Features - -* [Simple Declaration](https://fidelity.github.io/spock/docs/basic_tutorial/Define/): 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](https://fidelity.github.io/spock/docs/advanced_features/Inheritance/): Classes support - inheritance allowing for complex configurations derived from a common base set of parameters. -* [Complex Types](https://fidelity.github.io/spock/docs/advanced_features/Advanced-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](https://fidelity.github.io/spock/docs/advanced_features/Composition/): Compose from - multiple configuration files via simple include statements. -* [Command-Line Overrides](https://fidelity.github.io/spock/docs/advanced_features/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 (to the extent they can be in - Python). -* [Tractability and Reproducibility](https://fidelity.github.io/spock/docs/basic_tutorial/Saving/): 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](https://fidelity.github.io/spock/docs/addons/tuner/About.html): Provides a unified - interface for hyper-parameter tuning that supports various backends (Optuna, WIP: Ax) -* [S3 Addon](https://fidelity.github.io/spock/docs/addons/S3/): 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) -#### Main Contributors +### Original Implementation [Nicholas Cilfone](https://github.com/ncilfone), [Siddharth Narayanan](https://github.com/sidnarayanan) ___