Docs, custom constructor refinements (#194)

* Docs pass, primitive rule priority

* Fix default primitive rules

* tests

* sync docs

* union fix

docs/source/conf.py

@@ -395,6 +395,8 @@ def docstring(app, what, name, obj, options, lines):
     rst = m2r2.convert(md)
     lines.clear()
     lines += rst.splitlines()  # type: ignore
+    lines.append("")
+    lines.append("")
 
 
 def setup(app):

docs/source/examples/01_basics/03_dataclasses_defaults.rst

@@ -9,6 +9,7 @@ types.
 
 
 .. warning::
+
     We advise against mutation of configuration objects from a dataclass's
     :code:`__post_init__` method [#f1]_. In the example below,
     :code:`__post_init__` would be called twice: once for the :code:`Args()`

docs/source/examples/04_additional/06_generics_py312.rst

@@ -1,13 +1,14 @@
 .. Comment: this file is automatically generated by `update_example_docs.py`.
    It should not be modified manually.
 
-Generic Types (Python 3.12+ syntax)
+Generic Types (Python 3.12+)
 ==========================================
 
 Example of parsing for generic dataclasses using syntax introduced in Python
 3.12 (`PEP 695 <https://peps.python.org/pep-0695/>`_).
 
 .. warning::
+
     If used in conjunction with :code:`from __future__ import annotations`, the updated type parameter syntax requires Python 3.12.4 or newer. For technical details, see `this CPython PR <https://github.com/python/cpython/pull/118009>`_.
 
 

docs/source/examples/04_additional/17_aliases.rst → docs/source/examples/04_additional/11_aliases.rst

@@ -43,54 +43,54 @@ Argument Aliases
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py --help</kbd>
+        <kbd>python 04_additional/11_aliases.py --help</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py --help
+.. program-output:: python ../../examples/04_additional/11_aliases.py --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py commit --help</kbd>
+        <kbd>python 04_additional/11_aliases.py commit --help</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py commit --help
+.. program-output:: python ../../examples/04_additional/11_aliases.py commit --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py commit --message hello --all</kbd>
+        <kbd>python 04_additional/11_aliases.py commit --message hello --all</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py commit --message hello --all
+.. program-output:: python ../../examples/04_additional/11_aliases.py commit --message hello --all
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py commit -m hello -a</kbd>
+        <kbd>python 04_additional/11_aliases.py commit -m hello -a</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py commit -m hello -a
+.. program-output:: python ../../examples/04_additional/11_aliases.py commit -m hello -a
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py checkout --help</kbd>
+        <kbd>python 04_additional/11_aliases.py checkout --help</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py checkout --help
+.. program-output:: python ../../examples/04_additional/11_aliases.py checkout --help
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py checkout --branch main</kbd>
+        <kbd>python 04_additional/11_aliases.py checkout --branch main</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py checkout --branch main
+.. program-output:: python ../../examples/04_additional/11_aliases.py checkout --branch main
 
 ------------
 
 .. raw:: html
 
-        <kbd>python 04_additional/17_aliases.py checkout -b main</kbd>
+        <kbd>python 04_additional/11_aliases.py checkout -b main</kbd>
 
-.. program-output:: python ../../examples/04_additional/17_aliases.py checkout -b main
+.. program-output:: python ../../examples/04_additional/11_aliases.py checkout -b main

docs/source/examples/04_additional/16_type_statement.rst → docs/source/examples/04_additional/12_type_statement.rst

@@ -45,6 +45,6 @@ In Python 3.12, the :code:`type` statement is introduced to create type aliases.
 
 .. raw:: html
 
-        <kbd>python 04_additional/16_type_statement.py --help</kbd>
+        <kbd>python 04_additional/12_type_statement.py --help</kbd>
 
-.. program-output:: python ../../examples/04_additional/16_type_statement.py --help
+.. program-output:: python ../../examples/04_additional/12_type_statement.py --help

docs/source/examples/05_custom_constructors/01_primitive_annotation.rst

@@ -0,0 +1,71 @@
+.. Comment: this file is automatically generated by `update_example_docs.py`.
+   It should not be modified manually.
+
+Custom Primitive
+==========================================
+
+For additional flexibility, :mod:`tyro.constructors` exposes tyro's API for
+defining behavior for different types. There are two categories of types:
+primitive types can be instantiated from a single commandline argument, while
+struct types are broken down into multiple.
+
+In this example, we attach a custom constructor via a runtime annotation.
+
+
+.. code-block:: python
+        :linenos:
+
+
+        import json
+
+        from typing_extensions import Annotated
+
+        import tyro
+
+        # A dictionary type, but `tyro` will expect a JSON string from the CLI.
+        JsonDict = Annotated[
+            dict,
+            tyro.constructors.PrimitiveConstructorSpec(
+                nargs=1,
+                metavar="JSON",
+                instance_from_str=lambda args: json.loads(args[0]),
+                is_instance=lambda instance: isinstance(instance, dict),
+                str_from_instance=lambda instance: [json.dumps(instance)],
+            ),
+        ]
+
+
+        def main(
+            dict1: JsonDict,
+            dict2: JsonDict = {"default": None},
+        ) -> None:
+            print(f"{dict1=}")
+            print(f"{dict2=}")
+
+
+        if __name__ == "__main__":
+            tyro.cli(main)
+
+------------
+
+.. raw:: html
+
+        <kbd>python 05_custom_constructors/01_primitive_annotation.py --help</kbd>
+
+.. program-output:: python ../../examples/05_custom_constructors/01_primitive_annotation.py --help
+
+------------
+
+.. raw:: html
+
+        <kbd>python 05_custom_constructors/01_primitive_annotation.py --dict1 '{"hello": "world"}'</kbd>
+
+.. program-output:: python ../../examples/05_custom_constructors/01_primitive_annotation.py --dict1 '{"hello": "world"}'
+
+------------
+
+.. raw:: html
+
+        <kbd>python 05_custom_constructors/01_primitive_annotation.py --dict1 '{"hello": "world"}' --dict2 '{"hello": "world"}'</kbd>
+
+.. program-output:: python ../../examples/05_custom_constructors/01_primitive_annotation.py --dict1 '{"hello": "world"}' --dict2 '{"hello": "world"}'