refined website

.gitignore

@@ -133,4 +133,6 @@ dmypy.json
 .DS_Store
 
 # temp files
-tmp/
+tmp/
+Gemfile.lock
+_site/*

Gemfile

@@ -0,0 +1,31 @@
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+
+gem "jekyll-theme-minimal"
+
+
+# Following instructions from here: https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll
+# gem "jekyll", "~> 4.2.1"
+group :jekyll_plugins do
+  gem "jekyll-remote-theme"
+  gem "github-pages", "~> 219"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", "~> 1.2"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+gem "webrick", "~> 1.7"

README.md

@@ -1,14 +1,15 @@
-
 # Springs
 
+![springs_logo](https://github.com/soldni/springs/raw/main/assets/img/logo.png){:#hero}
+
 A set of utilities to turn [OmegaConf][1] into a fully fledge configuration utils.
-Just like the springs inside an Omega watch, they help you move with your experiments.
+Just like the springs inside an Omega watch, the Springs library helps you move on with your experiments.
 
 Springs overlaps in functionality with [Hydra][2], but without all the unnecessary boilerplate.
 
 The current logo for Springs was generated using [DALL·E 2][5].
 
-To install Springs, simply run
+To install Springs from [PyPI][6], simply run:
 
 ```bash
 pip install springs
@@ -26,33 +27,33 @@ We start by writing the following structure configuration
 import springs as sp
 from dataclasses import dataclass
 
-# this sub-config is for
-# data settings
-@dataclass
+# Data config
+# sp.dataclass is an alias for
+# dataclasses.dataclass
+@sp.dataclass
 class DataConfig:
     # sp.MISSING is an alias to
     # omegaconf.MISSING
     path: str = sp.MISSING
     split: str = 'train'
 
-# this sub-config is for
-# model settings
-@dataclass
+# Model config
+@sp.dataclass
 class ModelConfig:
     name: str = sp.MISSING
     num_labels: int = 2
 
 
-# this sub-config is for
-# experiment settings
-@dataclass
+# Experiment config
+@sp.dataclass
 class ExperimentConfig:
     batch_size: int = 16
     seed: int = 42
 
 
-# this is our overall config
-@dataclass
+# Overall config
+# for our program
+@sp.dataclass
 class Config:
     data: DataConfig = DataConfig()
     model: ModelConfig = ModelConfig()
@@ -117,7 +118,7 @@ python main.py -c config.yaml
 Easy, right?
 
 
-### Fine, We Do Support Support Unstructured Configurations
+### Fine, We Do Support Support Unstructured Configs!
 
 You are not required to used a structured config with Springs.
 To use our CLI with a bunch of yaml files and/or command line arguments, simply decorate your main function with no arguments.
@@ -137,7 +138,7 @@ instantiate an object from it.
 Springs supports this use case, and it is as easy as providing a `_target_` node in a configuration:
 
 ```python
-@dataclass
+@sp.dataclass
 class ModelConfig:
     _target_: str = (
         'transformers.'
@@ -154,13 +155,13 @@ In your experiment code, run:
 ```python
 def run_model(model_config: ModelConfig):
     ...
-    model = sp.init.now(model_config, ModelConfig)
+    model = sp.init.now(
+        model_config, ModelConfig
+    )
 ```
 
-**Note:** Previous versions of Springs supported specifying the return type,
-but now it is actively encouraged. Running `sp.init.now(model_config)` will
-now raise a warning if the type is not provided. To prevent this warning,
-use `sp.toggle_warnings(False)` before calling `sp.init.now`/ `sp.init.later`.
+**Note:** While previous versions of Springs merely supported specifying the return type, now it is actively and strongly encouraged.
+Running `sp.init.now(model_config)` will raise a warning if the type is not provided. To prevent this warning, use `sp.toggle_warnings(False)` before calling `sp.init.now`/ `sp.init.later`.
 
 ### `init.now` vs `init.later`
 
@@ -188,7 +189,7 @@ If, for some reason, cannot specify the path to a class as a string, you can use
 ```python
 import transformers
 
-@dataclass
+@sp.dataclass
 class ModelConfig:
     _target_: str = sp.Target.to_string(
         transformers.
@@ -208,7 +209,9 @@ To enable it, pass the expected return type when initializing an object:
 ```python
 @sp.cli(TokenizerConfig)
 def main(config: TokenizerConfig):
-    tokenizer = sp.init(config, PreTrainedTokenizerBase)
+    tokenizer = sp.init(
+        config, PreTrainedTokenizerBase
+    )
     print(tokenizer)
 ```
 
@@ -220,13 +223,12 @@ This will raise an error when the tokenizer is not a subclass of `PreTrainedToke
 Sometimes a configuration has some default parameters, but others are optional and depend on other factors, such as the `_target_` class.  In these cases, it is convenient to set up a flexible dataclass, using `make_flexy` after the `dataclass` decorator.
 
 ```python
-@sp.make_flexy
-@dataclass
+@sp.flexyclass
 class MetricConfig:
     _target_: str = sp.MISSING
     average: str = 'macro'
 
-config = sp.from_flexyclass(MetricConfig)
+config = sp.from_dataclass(MetricConfig)
 overrides = {
     # we override the _target_
     '_target_': 'torchmetrics.F1Score',
@@ -235,7 +237,8 @@ overrides = {
     'num_classes': 2
 }
 
-config = sp.merge(config, sp.from_dict(overrides))
+config = sp.merge(config,
+                  sp.from_dict(overrides))
 print(config)
 # this will print the following:
 # {
@@ -245,13 +248,6 @@ print(config)
 # }
 ```
 
-**Note:** In previous version of Springs, the canonical way to create a flexible class was to decorate a class with `@sp.flexyclass`. This method is still there, but it is not encouraged since it creates issues with `mypy` (and potentially other type checkers). Please consider switching to `dataclass` followed by `make_flexy`. To prevent a warning being raised for this, use
-`sp.toggle_warnings(False)` before calling `sp.flexyclass`.
-
-### Resolvers
-
-Guide coming soon!
-
 ## Tips and Tricks
 
 This section includes a bunch of tips and tricks for working with OmegaConf and YAML.
@@ -299,3 +295,4 @@ test_config:
 [3]: https://devblogs.microsoft.com/python/announcing-pylance-fast-feature-rich-language-support-for-python-in-visual-studio-code/
 [4]: https://code.visualstudio.com
 [5]: https://openai.com/dall-e-2/
+[6]: https://pypi.org/project/springs/

_config.yml

@@ -1,6 +1,5 @@
 theme: jekyll-theme-minimal
-
 title: Springs
-description: A set of utilities to turn Dataclasses into useful configuration managers.
-logo: /static/logo.png
+description: A set of utilities to create and manage typed configuration files effectively, built on top of OmegaConf.
+logo: /assets/img/logo.png
 google_analytics: G-LXRX72YD7R

_includes/head-custom-google-analytics.html

@@ -0,0 +1,9 @@
+<!-- Global site tag (gtag.js) - Google Analytics -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-NZ0CWS6R60"></script>
+<script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag() { dataLayer.push(arguments); }
+    gtag('js', new Date());
+
+    gtag('config', 'G-LXRX72YD7R');
+</script>

assets/css/style.scss

@@ -0,0 +1,95 @@
+---
+---
+
+@import "{{ site.theme }}";
+
+@import url('https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400;1,700&display=swap');
+
+
+header {
+    font-family: 'Atkinson Hyperlegible', sans-serif;
+    font-size: 90%;
+    line-height: 1.3;
+    p {
+        text-align: left;
+    }
+
+    h1 {
+        font-size: 2.5em;
+    }
+
+    @media(max-width: 960px) {
+      text-align: center;
+      padding: 0;
+      p {text-align: center}
+      h1 {text-align: center}
+
+      // float: center;
+      // margin-top: -8px;
+      // margin-left: auto;
+      // margin-right: auto;
+    }
+}
+
+body {
+  text-align: justify;
+
+  font-family: 'Atkinson Hyperlegible', sans-serif;
+  font-size: 100%;
+  line-height: 1.3;
+
+  // hide title when not on github
+  h1#springs {
+    visibility: hidden;
+    height: 0px;
+    margin-top: 0;
+    margin-bottom: -1.5em;
+  }
+  img#hero{
+    visibility: hidden;
+    height: 0px;
+  }
+
+}
+
+
+
+h1, h2, h3, h4, h5, h6 {
+  text-align: left;
+}
+
+li {
+  text-align: left;
+}
+
+
+/* mouse over link */
+a:hover {
+  color: #CA3B7D;
+  font-style: normal;
+  font-weight: normal;
+  text-decoration: none;
+}
+
+code {
+  font-size: .8em;
+}
+
+
+h1 {
+    a:hover {
+    font-weight: bold;
+    text-decoration: none;
+  }
+}
+
+p.view {
+  margin-top: 5em;
+  @media(max-width: 960px) {
+    margin-top: 1em;
+  }
+}
+
+footer {
+  visibility: hidden;
+}

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "springs"
-version = "1.4"
-description = "A set of utilities to create and manage configuration files effectively, built on top of OmegaConf."
+version = "1.4.1"
+description = "A set of utilities to create and manage typed configuration files effectively, built on top of OmegaConf."
 authors = [
     {name = "Luca Soldaini", email = "[email protected]" }
 ]

scripts/preview-website.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# get script directory
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  SCRIPT_DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  # if $SOURCE was a relative symlink, we need to resolve it
+  # relative to the path where the symlink file was located
+  [[ $SOURCE != /* ]] && SOURCE="$SCRIPT_DIR/$SOURCE"
+done
+SCRIPT_DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+
+bundle install && bundle exec jekyll serve