Add API reference documentation using mkdocstrings

docs/api_reference.md

@@ -0,0 +1,29 @@
+# API Reference
+
+This section provides an auto-generated API reference for the `simple_parsing` library.
+
+## Core Parsing Logic
+
+::: simple_parsing.parsing
+
+## Serializable Objects
+
+::: simple_parsing.helpers.serialization.serializable.Serializable
+
+## Dataclass Utilities
+
+::: simple_parsing.wrappers.dataclass_wrapper
+
+## Field Wrappers
+
+::: simple_parsing.wrappers.field_wrapper
+
+## ArgumentParser
+
+::: simple_parsing.ArgumentParser
+
+## Other Helpers
+
+You can add more specific modules or classes here as needed.
+For example, to document the `simple_parsing.helpers.hparams` module:
+::: simple_parsing.helpers.hparams

docs/examples/ML/README.md

@@ -0,0 +1,90 @@
+## Use-Case Example: ML Scripts
+
+Let's look at a great use-case for `simple-parsing`: ugly ML code:
+
+### Before:
+
+```python
+import argparse
+
+parser = argparse.ArgumentParser()
+
+# hyperparameters
+parser.add_argument("--learning_rate", type=float, default=0.05)
+parser.add_argument("--momentum", type=float, default=0.01)
+# (... other hyperparameters here)
+
+# args for training config
+parser.add_argument("--data_dir", type=str, default="/data")
+parser.add_argument("--log_dir", type=str, default="/logs")
+parser.add_argument("--checkpoint_dir", type=str, default="checkpoints")
+
+args = parser.parse_args()
+
+learning_rate = args.learning_rate
+momentum = args.momentum
+# (...) dereference all the variables here, without any typing
+data_dir = args.data_dir
+log_dir = args.log_dir
+checkpoint_dir = args.checkpoint_dir
+
+class MyModel():
+    def __init__(self, data_dir, log_dir, checkpoint_dir, learning_rate, momentum, *args):
+        # config:
+        self.data_dir = data_dir
+        self.log_dir = log_dir
+        self.checkpoint_dir = checkpoint_dir
+
+        # hyperparameters:
+        self.learning_rate = learning_rate
+        self.momentum = momentum
+
+m = MyModel(data_dir, log_dir, checkpoint_dir, learning_rate, momentum)
+# Ok, what if we wanted to add a new hyperparameter?!
+```
+
+### After:
+
+```python
+from dataclasses import dataclass
+from simple_parsing import ArgumentParser
+
+# create a parser, as usual
+parser = ArgumentParser()
+
+@dataclass
+class MyModelHyperParameters:
+    """Hyperparameters of MyModel"""
+    # Learning rate of the Adam optimizer.
+    learning_rate: float = 0.05
+    # Momentum of the optimizer.
+    momentum: float = 0.01
+
+@dataclass
+class TrainingConfig:
+    """Training configuration settings"""
+    data_dir: str = "/data"
+    log_dir: str = "/logs"
+    checkpoint_dir: str = "checkpoints"
+
+
+# automatically add arguments for all the fields of the classes above:
+parser.add_arguments(MyModelHyperParameters, dest="hparams")
+parser.add_arguments(TrainingConfig, dest="config")
+
+args = parser.parse_args()
+
+# Create an instance of each class and populate its values from the command line arguments:
+hyperparameters: MyModelHyperParameters = args.hparams
+config: TrainingConfig = args.config
+
+class MyModel():
+    def __init__(self, hyperparameters: MyModelHyperParameters, config: TrainingConfig):
+        # hyperparameters:
+        self.hyperparameters = hyperparameters
+        # config:
+        self.config = config
+
+m = MyModel(hyperparameters, config)
+
+```

docs/examples/ML/ml_example_after.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+
+from simple_parsing import ArgumentParser
+
+# create a parser, as usual
+parser = ArgumentParser()
+
+
+@dataclass
+class MyModelHyperParameters:
+    """Hyperparameters of MyModel."""
+
+    # Learning rate of the Adam optimizer.
+    learning_rate: float = 0.05
+    # Momentum of the optimizer.
+    momentum: float = 0.01
+
+
+@dataclass
+class TrainingConfig:
+    """Training configuration settings."""
+
+    data_dir: str = "/data"
+    log_dir: str = "/logs"
+    checkpoint_dir: str = "checkpoints"
+
+
+# automatically add arguments for all the fields of the classes above:
+parser.add_arguments(MyModelHyperParameters, dest="hparams")
+parser.add_arguments(TrainingConfig, dest="config")
+
+args = parser.parse_args()
+
+# Create an instance of each class and populate its values from the command line arguments:
+hyperparameters: MyModelHyperParameters = args.hparams
+config: TrainingConfig = args.config
+
+
+class MyModel:
+    def __init__(self, hyperparameters: MyModelHyperParameters, config: TrainingConfig):
+        # hyperparameters:
+        self.hyperparameters = hyperparameters
+        # config:
+        self.config = config
+
+
+m = MyModel(hyperparameters, config)

docs/examples/ML/ml_example_before.py

@@ -0,0 +1,38 @@
+from argparse import ArgumentParser
+
+parser = ArgumentParser()
+
+# hyperparameters
+parser.add_argument("--learning_rate", type=float, default=0.05)
+parser.add_argument("--momentum", type=float, default=0.01)
+# (... other hyperparameters here)
+
+# args for training config
+parser.add_argument("--data_dir", type=str, default="/data")
+parser.add_argument("--log_dir", type=str, default="/logs")
+parser.add_argument("--checkpoint_dir", type=str, default="checkpoints")
+
+args = parser.parse_args()
+
+learning_rate = args.learning_rate
+momentum = args.momentum
+# (...) dereference all the variables here, without any typing
+data_dir = args.data_dir
+log_dir = args.log_dir
+checkpoint_dir = args.checkpoint_dir
+
+
+class MyModel:
+    def __init__(self, data_dir, log_dir, checkpoint_dir, learning_rate, momentum, *args):
+        # config:
+        self.data_dir = data_dir
+        self.log_dir = log_dir
+        self.checkpoint_dir = checkpoint_dir
+
+        # hyperparameters:
+        self.learning_rate = learning_rate
+        self.momentum = momentum
+
+
+m = MyModel(data_dir, log_dir, checkpoint_dir, learning_rate, momentum)
+# Ok, what if we wanted to add a new hyperparameter?!

docs/examples/ML/other_ml_example.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass
+
+import simple_parsing
+
+# create a parser,
+parser = simple_parsing.ArgumentParser()
+
+
+@dataclass
+class MyModelHyperParameters:
+    """Hyperparameters of MyModel."""
+
+    # Batch size (per-GPU)
+    batch_size: int = 32
+    # Learning rate of the Adam optimizer.
+    learning_rate: float = 0.05
+    # Momentum of the optimizer.
+    momentum: float = 0.01
+
+
+@dataclass
+class TrainingConfig:
+    """Settings related to Training."""
+
+    data_dir: str = "data"
+    log_dir: str = "logs"
+    checkpoint_dir: str = "checkpoints"
+
+
+@dataclass
+class EvalConfig:
+    """Settings related to evaluation."""
+
+    eval_dir: str = "eval_data"
+
+
+# automatically add arguments for all the fields of the classes above:
+parser.add_arguments(MyModelHyperParameters, "hparams")
+parser.add_arguments(TrainingConfig, "train_config")
+parser.add_arguments(EvalConfig, "eval_config")
+
+# NOTE: `ArgumentParser` is just a subclass of `argparse.ArgumentParser`,
+# so we could add some other arguments as usual:
+# parser.add_argument(...)
+# parser.add_argument(...)
+# (...)
+# parser.add_argument(...)
+# parser.add_argument(...)
+
+args = parser.parse_args()
+
+# Retrieve the objects from the parsed args!
+hparams: MyModelHyperParameters = args.hparams
+train_config: TrainingConfig = args.train_config
+eval_config: EvalConfig = args.eval_config
+
+print(hparams, train_config, eval_config, sep="\n")
+expected = """
+MyModelHyperParameters(batch_size=32, learning_rate=0.05, momentum=0.01)
+TrainingConfig(data_dir='data', log_dir='logs', checkpoint_dir='checkpoints')
+EvalConfig(eval_dir='eval_data')
+"""

docs/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+- [dataclasses intro](dataclasses/README.md): Quick intro to Python's new [dataclasses](https://docs.python.org/3.7/library/dataclasses.html) module.
+
+- **[Simple example](simple/basic.py)**: Simple use-case example with a before/after comparison.
+
+- [ML-related Examples](ML/README.md)
+
+- **NEW**: [Subgroups Example](subgroups/README.md)
+
+<!-- - **NEW**: [Partials Example](partials/README.md) -->
+
+- [Serialization to `json`/`yaml`](serialization/README.md)
+
+- [Attribute Docstrings Example](docstrings/README.md)
+
+- [Parsing of lists and tuples](container_types/README.md)
+
+- [**Nesting**!!](nesting/README.md)
+
+- [Prefixing](prefixing/README.md)
+
+- [Enums Example](enums/README.md)
+
+- [Subparsers Example](subparsers/README.md)

docs/examples/aliases/README.md

@@ -0,0 +1,62 @@
+# Using Aliases
+
+## Notes about `option_strings`:
+
+Additional names for the same argument can be added via the `alias` argument
+of the `field` function (see [the custom_args Example](../custom_args/README.md) for more info).
+
+The `simple_parsing.ArgumentParser` accepts an argument (currently called `add_option_string_dash_variants`, which defaults to False) which adds additional variants to allow using either dashes or underscores to refer to an argument:
+
+- Whenever the name of an attribute includes underscores ("\_"), the same
+  argument can be passed by using dashes ("-") instead. This also includes
+  aliases.
+- If an alias contained leading dashes, either single or double, the
+  same number of dashes will be used, even in the case where a prefix is
+  added.
+  For instance, consider the following example.
+  Here we have two prefixes: `"train"` and `"valid"`.
+  The corresponding option_strings for each argument will be
+  `["--train.debug", "-train.d"]` and `["--valid.debug", "-valid.d"]`,
+  respectively, as shown here:
+
+```python
+from dataclasses import dataclass
+from simple_parsing import ArgumentParser, field
+
+@dataclass
+class RunSettings:
+    ''' Parameters for a run. '''
+    # whether or not to execute in debug mode.
+    debug: bool = field(alias=["-d"], default=False)
+    some_value: int = field(alias=["-v"], default=123)
+
+parser = ArgumentParser(add_option_string_dash_variants=True)
+parser.add_arguments(RunSettings, dest="train")
+parser.add_arguments(RunSettings, dest="valid")
+parser.print_help()
+
+# This prints:
+'''
+usage: test.py [-h] [--train.debug [bool]] [--train.some_value int]
+               [--valid.debug [bool]] [--valid.some_value int]
+
+optional arguments:
+  -h, --help            show this help message and exit
+
+RunSettings ['train']:
+  Parameters for a run.
+
+  --train.debug [bool], --train.d [bool]
+                        whether or not to execute in debug mode. (default:
+                        False)
+  --train.some_value int, --train.v int
+
+RunSettings ['valid']:
+  Parameters for a run.
+
+  --valid.debug [bool], --valid.d [bool]
+                        whether or not to execute in debug mode. (default:
+                        False)
+  --valid.some_value int, --valid.v int
+'''
+```