Documentation rework

brentyi · Oct 19, 2022 · fbefca6 · fbefca6
1 parent 5c3bc9a
commit fbefca6
Show file tree

Hide file tree

Showing 45 changed files with 568 additions and 235 deletions.
diff --git a/README.md b/README.md
@@ -2,9 +2,10 @@
 <p align="center">
     <!-- Note that image URLs should all be absolute; this README will be used for both GitHub and PyPI. -->
     <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="https://brentyi.github.io/tyro/_static/logo-dark.svg">
-    <img alt="tyro logo" src="https://brentyi.github.io/tyro/_static/logo-light.svg" width="200px">
-</picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://brentyi.github.io/tyro/_static/logo-dark.svg" />
+        <img alt="tyro logo" src="https://brentyi.github.io/tyro/_static/logo-light.svg" width="200px" />
+    </picture>
+</p>
 
 <p align="center">
     <em><a href="https://brentyi.github.io/tyro">Documentation</a></em>

diff --git a/docs/source/building_configuration_systems.md b/docs/source/building_configuration_systems.md
@@ -15,5 +15,4 @@ have multiple default configuration objects and need to select one to pass in as
 a default -- this might be a YAML file or config instance -- an environment
 variable or manually parsed (via `sys.argv`) positional argument can be used.
 
-For exposing each of these base configurations as subcommands, see our
-[base config example](/examples/10_base_configs).
+For concrete examples, see our "Config Management" documentation.
diff --git a/docs/source/examples/01_functions.rst → ...ource/examples/01_basics/01_functions.rst b/docs/source/examples/01_functions.rst → ...ource/examples/01_basics/01_functions.rst
@@ -1,7 +1,7 @@
 .. Comment: this file is automatically generated by `update_example_docs.py`.
    It should not be modified manually.
 
-1. Functions
+Functions
 ==========================================
 
 
@@ -37,22 +37,22 @@ populated from the CLI.
 
 .. raw:: html
 
-        <kbd>python 01_functions.py --help</kbd>
+        <kbd>python 01_basics/01_functions.py --help</kbd>
 
-.. program-output:: python ../../examples/01_functions.py --help
+.. program-output:: python ../../examples/01_basics/01_functions.py --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 01_functions.py --field1 hello</kbd>
+        <kbd>python 01_basics/01_functions.py --field1 hello</kbd>
 
-.. program-output:: python ../../examples/01_functions.py --field1 hello
+.. program-output:: python ../../examples/01_basics/01_functions.py --field1 hello
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 01_functions.py --field1 hello --field2 10</kbd>
+        <kbd>python 01_basics/01_functions.py --field1 hello --field2 10</kbd>
 
-.. program-output:: python ../../examples/01_functions.py --field1 hello --field2 10
+.. program-output:: python ../../examples/01_basics/01_functions.py --field1 hello --field2 10
diff --git a/docs/source/examples/02_dataclasses.rst → ...rce/examples/01_basics/02_dataclasses.rst b/docs/source/examples/02_dataclasses.rst → ...rce/examples/01_basics/02_dataclasses.rst
@@ -1,7 +1,7 @@
 .. Comment: this file is automatically generated by `update_example_docs.py`.
    It should not be modified manually.
 
-2. Dataclasses
+Dataclasses
 ==========================================
 
 
@@ -24,8 +24,11 @@ can be used as a typed alternative for an argparse namespace.
             """Description.
             This should show up in the helptext!"""
 
-            field1: str  # A string field.
-            field2: int = 3  # A numeric field, with a default value.
+            field1: str
+            """A string field."""
+
+            field2: int = 3
+            """A numeric field, with a default value."""
 
 
         if __name__ == "__main__":
@@ -36,22 +39,22 @@ can be used as a typed alternative for an argparse namespace.
 
 .. raw:: html
 
-        <kbd>python 02_dataclasses.py --help</kbd>
+        <kbd>python 01_basics/02_dataclasses.py --help</kbd>
 
-.. program-output:: python ../../examples/02_dataclasses.py --help
+.. program-output:: python ../../examples/01_basics/02_dataclasses.py --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 02_dataclasses.py --field1 hello</kbd>
+        <kbd>python 01_basics/02_dataclasses.py --field1 hello</kbd>
 
-.. program-output:: python ../../examples/02_dataclasses.py --field1 hello
+.. program-output:: python ../../examples/01_basics/02_dataclasses.py --field1 hello
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 02_dataclasses.py --field1 hello --field2 5</kbd>
+        <kbd>python 01_basics/02_dataclasses.py --field1 hello --field2 5</kbd>
 
-.. program-output:: python ../../examples/02_dataclasses.py --field1 hello --field2 5
+.. program-output:: python ../../examples/01_basics/02_dataclasses.py --field1 hello --field2 5
diff --git a/...urce/examples/03_enums_and_containers.rst → ...urce/examples/01_basics/03_containers.rst b/...urce/examples/03_enums_and_containers.rst → ...urce/examples/01_basics/03_containers.rst
@@ -1,12 +1,13 @@
 .. Comment: this file is automatically generated by `update_example_docs.py`.
    It should not be modified manually.
 
-3. Enums And Containers
+Containers
 ==========================================
 
 
-We can generate argument parsers from more advanced type annotations, like enums and
-container types.
+Arguments of both fixed and variable lengths can be annotated with standard Python
+container types; such as ``typing.List[T]`` or ``typing.Tuple[T1, T2]``. In Python 3.9,
+``list[T]`` and ``tuple[T]`` are also directly supported.
 
 
 
@@ -38,14 +39,6 @@ container types.
             image_dimensions: Tuple[int, int] = (32, 32)
             """Height and width of some image data."""
 
-            # Enums are handled seamlessly.
-            optimizer_type: OptimizerType = OptimizerType.ADAM
-            """Gradient-based optimizer to use."""
-
-            # We can also explicitly mark arguments as optional.
-            checkpoint_interval: Optional[int] = None
-            """Interval to save checkpoints at."""
-
 
         if __name__ == "__main__":
             config = tyro.cli(TrainConfig)
@@ -55,22 +48,22 @@ container types.
 
 .. raw:: html
 
-        <kbd>python 03_enums_and_containers.py --help</kbd>
+        <kbd>python 01_basics/03_containers.py --help</kbd>
 
-.. program-output:: python ../../examples/03_enums_and_containers.py --help
+.. program-output:: python ../../examples/01_basics/03_containers.py --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 03_enums_and_containers.py --dataset-sources ./data --image-dimensions 16 16</kbd>
+        <kbd>python 01_basics/03_containers.py --dataset-sources ./data --image-dimensions 16 16</kbd>
 
-.. program-output:: python ../../examples/03_enums_and_containers.py --dataset-sources ./data --image-dimensions 16 16
+.. program-output:: python ../../examples/01_basics/03_containers.py --dataset-sources ./data --image-dimensions 16 16
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 03_enums_and_containers.py --dataset-sources ./data --optimizer-type SGD</kbd>
+        <kbd>python 01_basics/03_containers.py --dataset-sources ./data</kbd>
 
-.. program-output:: python ../../examples/03_enums_and_containers.py --dataset-sources ./data --optimizer-type SGD
+.. program-output:: python ../../examples/01_basics/03_containers.py --dataset-sources ./data
diff --git a/docs/source/examples/01_basics/04_enums.rst b/docs/source/examples/01_basics/04_enums.rst
@@ -0,0 +1,65 @@
+.. Comment: this file is automatically generated by `update_example_docs.py`.
+   It should not be modified manually.
+
+Enums
+==========================================
+
+
+We can generate argument parsers from more advanced type annotations, like enums.
+
+
+
+.. code-block:: python
+        :linenos:
+
+
+        import dataclasses
+        import enum
+        import pathlib
+        from typing import Optional, Tuple
+
+        import tyro
+
+
+        class OptimizerType(enum.Enum):
+            ADAM = enum.auto()
+            SGD = enum.auto()
+
+
+        @dataclasses.dataclass(frozen=True)
+        class TrainConfig:
+            # Enums are handled seamlessly.
+            optimizer_type: OptimizerType = OptimizerType.ADAM
+            """Gradient-based optimizer to use."""
+
+            learning_rate: float = 1e-4
+            """Learning rate for optimizer."""
+
+
+        if __name__ == "__main__":
+            config = tyro.cli(TrainConfig)
+            print(config)
+
+------------
+
+.. raw:: html
+
+        <kbd>python 01_basics/04_enums.py --help</kbd>
+
+.. program-output:: python ../../examples/01_basics/04_enums.py --help
+
+------------
+
+.. raw:: html
+
+        <kbd>python 01_basics/04_enums.py --optimizer-type SGD</kbd>
+
+.. program-output:: python ../../examples/01_basics/04_enums.py --optimizer-type SGD
+
+------------
+
+.. raw:: html
+
+        <kbd>python 01_basics/04_enums.py --optimizer-type ADAM --learning-rate 3e-4</kbd>
+
+.. program-output:: python ../../examples/01_basics/04_enums.py --optimizer-type ADAM --learning-rate 3e-4
diff --git a/docs/source/examples/04_flags.rst → docs/source/examples/01_basics/05_flags.rst b/docs/source/examples/04_flags.rst → docs/source/examples/01_basics/05_flags.rst
@@ -1,7 +1,7 @@
 .. Comment: this file is automatically generated by `update_example_docs.py`.
    It should not be modified manually.
 
-4. Flags
+Booleans and Flags
 ==========================================
 
 
@@ -45,30 +45,30 @@ To turn off conversion, see :class:`tyro.conf.FlagConversionOff`.
 
 .. raw:: html
 
-        <kbd>python 04_flags.py --help</kbd>
+        <kbd>python 01_basics/05_flags.py --help</kbd>
 
-.. program-output:: python ../../examples/04_flags.py --help
+.. program-output:: python ../../examples/01_basics/05_flags.py --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_flags.py --boolean True</kbd>
+        <kbd>python 01_basics/05_flags.py --boolean True</kbd>
 
-.. program-output:: python ../../examples/04_flags.py --boolean True
+.. program-output:: python ../../examples/01_basics/05_flags.py --boolean True
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_flags.py --boolean False --flag-a</kbd>
+        <kbd>python 01_basics/05_flags.py --boolean False --flag-a</kbd>
 
-.. program-output:: python ../../examples/04_flags.py --boolean False --flag-a
+.. program-output:: python ../../examples/01_basics/05_flags.py --boolean False --flag-a
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_flags.py --boolean False --no-flag-b</kbd>
+        <kbd>python 01_basics/05_flags.py --boolean False --no-flag-b</kbd>
 
-.. program-output:: python ../../examples/04_flags.py --boolean False --no-flag-b
+.. program-output:: python ../../examples/01_basics/05_flags.py --boolean False --no-flag-b
diff --git a/docs/source/examples/01_basics/06_literals.rst b/docs/source/examples/01_basics/06_literals.rst
@@ -0,0 +1,49 @@
+.. Comment: this file is automatically generated by `update_example_docs.py`.
+   It should not be modified manually.
+
+Choices
+==========================================
+
+
+``typing.Literal[]`` can be used to restrict inputs to a fixed set of literal choices.
+
+
+
+.. code-block:: python
+        :linenos:
+
+
+        import dataclasses
+        import enum
+        from typing import Literal, Optional, Tuple, Union
+
+        import tyro
+
+
+        class Color(enum.Enum):
+            RED = enum.auto()
+            GREEN = enum.auto()
+            BLUE = enum.auto()
+
+
+        @dataclasses.dataclass(frozen=True)
+        class Args:
+            # We can use Literal[] to restrict the set of allowable inputs, for example, over
+            # enums.
+            restricted_enum: Literal[Color.RED, Color.GREEN] = Color.RED
+
+            # Or mix them with other types!
+            mixed: Literal[Color.RED, Color.GREEN, "blue"] = "blue"
+
+
+        if __name__ == "__main__":
+            args = tyro.cli(Args)
+            print(args)
+
+------------
+
+.. raw:: html
+
+        <kbd>python 01_basics/06_literals.py --help</kbd>
+
+.. program-output:: python ../../examples/01_basics/06_literals.py --help
diff --git a/...ource/examples/06_literals_and_unions.rst → docs/source/examples/01_basics/07_unions.rst b/...ource/examples/06_literals_and_unions.rst → docs/source/examples/01_basics/07_unions.rst
@@ -1,12 +1,11 @@
 .. Comment: this file is automatically generated by `update_example_docs.py`.
    It should not be modified manually.
 
-6. Literals And Unions
+Unions
 ==========================================
 
 
-``typing.Literal[]`` can be used to restrict inputs to a fixed set of literal choices;
-``typing.Union[]`` can be used to restrict inputs to a fixed set of types.
+``typing.Union[]`` can be used to expand inputs to multiple types.
 
 
 
@@ -29,16 +28,6 @@
 
         @dataclasses.dataclass(frozen=True)
         class Args:
-            # We can use Literal[] to restrict the set of allowable inputs, for example, over
-            # enums.
-            restricted_enum: Literal[Color.RED, Color.GREEN] = Color.RED
-
-            # Or mix them with other types!
-            mixed: Literal[Color.RED, Color.GREEN, "blue"] = "blue"
-
-            # Literals can also be marked Optional.
-            integer: Optional[Literal[0, 1, 2, 3]] = None
-
             # Unions can be used to specify multiple allowable types.
             union_over_types: Union[int, str] = 0
             string_or_enum: Union[Literal["red", "green"], Color] = "red"
@@ -52,6 +41,9 @@
                 Color.RED,
             )
 
+            # Optional[T] is equivalent to Union[T, None].
+            integer: Optional[Literal[0, 1, 2, 3]] = None
+
 
         if __name__ == "__main__":
             args = tyro.cli(Args)
@@ -61,6 +53,6 @@
 
 .. raw:: html
 
-        <kbd>python 06_literals_and_unions.py --help</kbd>
+        <kbd>python 01_basics/07_unions.py --help</kbd>
 
-.. program-output:: python ../../examples/06_literals_and_unions.py --help
+.. program-output:: python ../../examples/01_basics/07_unions.py --help