Improve landing page docs (#210)

* fix typo in docs

* add rst anchors for internal links

* add hydra-zen bells and whistles, at a glance, and comparison to Hydra

* sync readme

* Rework intro

* Remove custom css

README.md

@@ -37,12 +37,20 @@ hydra-zen is a Python library that simplifies the process of writing code (resea
 - **Repeatable**: each run of your code will be self-documenting; the full configuration of your software is saved alongside your results.
 - **Scalable**: launch multiple runs of your software, be it on your local machine or across multiple nodes on a cluster.
 
-It builds off – and is fully compatible with – [Hydra](https://hydra.cc/), a framework for elegantly 
-configuring complex applications. 
 
-hydra-zen helps simplify the process of using Hydra by providing 
-convenient functions for creating and validating configs, as well as launching Hydra jobs. It also provides novel 
-functionality such as wrapped instantiation and meta fields in configs.
+It builds off – and is fully compatible with – [Hydra](https://hydra.cc/), a framework for elegantly 
+configuring complex applications. hydra-zen helps simplify the 
+process of using Hydra by providing specialized functions for :ref:`creating configs <create-config>` and 
+launching Hydra jobs. 
+
+hydra-zen also also provides Hydra users with powerful, novel functionality. With it, we can:
+
+- Add enhanced runtime type-checking for our Hydra application, via pydantic, beartype, and other third-party libraries.
+- Design configs with specialized behaviors, like partial configs, or configs with meta-fields. 
+- Use additional data types in our configs, like `pathlib.Path`, that are not natively supported by Hydra.
+- Validate our configs at runtime, prior to launching our application.
+- Leverage a powerful functionality-injection framework in our Hydra applications.
+- Run static type-checkers on our config-creation code to catch incompatibilities with Hydra.
 
 ## Installation
 `hydra-zen` is lightweight: its only dependencies are `hydra-core` and `typing-extensions`.

docs/source/conf.py

@@ -117,7 +117,6 @@
 
 
 def setup(app):
-    app.add_css_file("my_theme.css")
     app.add_js_file(
         "https://www.googletagmanager.com/gtag/js?id=UA-115029372-2",
         loading_method="async",

docs/source/explanation/dont_repeat_yourself.rst

@@ -1,6 +1,7 @@
 .. meta::
    :description: hydra-zen eliminates the repetitive patterns involved in designing a Hydra-based project by providing users with functions for dynamically generating configurations for their project.
 
+.. _dry:
 
 ========================================================================
 Don't Repeat Yourself: Keeping DRY with Dynamically-Generated Configs 🌞

docs/source/explanation/type_refinement.rst

@@ -100,6 +100,8 @@ In this way, we can still configure and build this function, but we also retain
 In general, hydra-zen will broaden types as-needed so that dynamically-generated configs will never include annotations that would cause Hydra to raise an error due
 to lack of support for that type.
 
+.. _pydantic-support:
+
 Using Third-Party Runtime Type-Checkers
 ---------------------------------------
 Although hydra-zen will broaden the types that get exposed to Hydra, the original 

docs/source/how_to/beartype.rst

@@ -5,6 +5,8 @@
 
    Your must install `beartype <https://github.com/beartype/beartype>`_ in your Python environment in order to complete this How-To guide.
 
+.. _runtime-type-checking:
+
 =================================================
 Add Enhanced Runtime Type-Checking to a Hydra App
 =================================================

docs/source/index.rst

@@ -3,31 +3,71 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+
+.. admonition:: Join the Discussion 💬
+
+   Share ideas, ask questions, and chat with us over at `hydra-zen's discussion board <https://github.com/mit-ll-responsible-ai/hydra-zen/discussions>`_.
+
+
+.. tip::
+
+   🎓 Using hydra-zen for your research project? `Cite us <https://zenodo.org/record/5584711>`_!
+
+
 =====================================
 Welcome to hydra-zen's documentation!
 =====================================
 
 hydra-zen is a Python library that simplifies the process of writing code (be it research-grade or production-grade) that is:
 
-- **Configurable**: you can configure all aspects of your code from a single interface (the command line or a Python function).
+- **Configurable**: change deeply-nested parameters and swap out entire pieces of your program, all from the command line. 
 - **Repeatable**: each run of your code will be self-documenting; the full configuration of your software is saved alongside your results.
 - **Scalable**: launch multiple runs of your software, be it on your local machine or across multiple nodes on a cluster.
 
 It builds off -- and is fully compatible with -- `Hydra <https://hydra.cc/>`_, a 
 framework for elegantly configuring complex applications. hydra-zen helps simplify the 
-process of using Hydra by providing convenient functions for creating configs and 
-launching Hydra jobs. It also provides novel functionality such as 
-:ref:`wrapped instantiation <zen-wrapper>` and :ref:`meta fields <meta-field>` in configs.
-
-.. admonition:: Join the Discussion 💬
-
-   Share ideas, ask questions, and chat with us over at `hydra-zen's discussion board <https://github.com/mit-ll-responsible-ai/hydra-zen/discussions>`_.
+process of using Hydra by providing specialized functions for :ref:`creating configs <create-config>` and 
+launching Hydra jobs. 
+
+
+.. admonition:: Attention, Hydra users:
+
+  If you are already use Hydra, let's cut to the chase: **the most important benefit of using hydra-zen is that it automatically and dynamically generates structured configs for you**.
+
+
+  +----------------------------------------------------------------+-----------------------------------------------------------------------+
+  | .. code-block:: python                                         | .. code-block:: python                                                |
+  |    :caption: Creating a structured config using vanilla Hydra  |    :caption: Creating an equivalent structured config using hydra-zen |
+  |                                                                |                                                                       |
+  |    from dataclasses import dataclass, field                    |    from hydra_zen import builds                                       |
+  |                                                                |                                                                       |
+  |    def foo(bar: int, baz: list[str], qux: float = 1.23):       |    def foo(bar: int, baz: list[str], qux: float = 1.23):              |
+  |        ...                                                     |        ...                                                            |
+  |                                                                |                                                                       |
+  |    @dataclass                                                  |    FooConf = builds(foo, bar=2, baz=["abc"],                          |
+  |    class FooConf:                                              |                     populate_full_signature=True)                     |
+  |        _target_: str = "__main__.foo"                          |                                                                       |
+  |        bar: int = 2                                            |                                                                       |
+  |        baz: list[str] = field(default_factory=lambda: ["abc"]) |                                                                       |
+  |        qux: float = 1.23                                       |                                                                       |
+  +----------------------------------------------------------------+-----------------------------------------------------------------------+
+
+  This means that it is much **easier and safer** to write and maintain the configs for your Hydra applications:
+
+  - Write all of your configs in Python. No more yaml files!
+  - Write less, :ref:`stop repeating yourself <dry>`, and get more out of your configs.
+  - Get automatic type-safety via :func:`~hydra_zen.builds`'s signature inspection.
+  - :ref:`Validate your configs <builds-validation>` before launching your application.
+
+hydra-zen also also provides Hydra users with powerful, novel functionality. With it, we can:
+
+- Add :ref:`enhanced runtime type-checking <runtime-type-checking>` for our Hydra application, via :ref:`pydantic <pydantic-support>`, `beartype <https://github.com/beartype/beartype>`_, and other third-party libraries.
+- Design configs with specialized behaviors, like :ref:`partial configs <partial-config>`, or :ref:`configs with meta-fields <meta-field>`. 
+- Use :ref:`additional data types <additional-types>` in our configs, like :py:class:`pathlib.Path`, that are not natively supported by Hydra.
+- Leverage a powerful :ref:`functionality-injection framework <zen-wrapper>` in our Hydra applications.
+- Run static type-checkers on our config-creation code to catch incompatibilities with Hydra.
 
 
-.. tip::
-
-   🎓 Using hydra-zen for your research project? `Cite us <https://zenodo.org/record/5584711>`_!
-
 Installation
 ============
 
@@ -45,6 +85,7 @@ the latest pre-release of hydra-zen with:
 
    $ pip install --pre hydra-zen
 
+
 Learning About hydra-zen
 ========================
 

docs/source/tutorials.rst

@@ -1,6 +1,8 @@
 .. meta::
    :description: Tutorials for getting started with Hydra and hydra-zen.
 
+.. _tutorials:
+
 Tutorials
 =========
 

src/hydra_zen/structured_configs/_implementations.py

@@ -784,7 +784,7 @@ def builds(
         I.e. setting/deleting an attribute of an instance will raise
         :py:class:`dataclasses.FrozenInstanceError` at runtime.
 
-    builds_bases : Tuple[DataClass, ...]
+    builds_bases : Tuple[Type[DataClass], ...]
         Specifies a tuple of parent classes that the resulting config inherits from.
         A ``PartialBuilds`` class (resulting from ``zen_partial=True``) cannot be a
         parent of a ``Builds`` class (i.e. where `zen_partial=False` was specified).
@@ -953,6 +953,10 @@ def builds(
     >>> builds(func, 1, builds_bases=(BaseConf,))  # too many args (via inheritance)
     TypeError: Building: func ..
 
+    >>> builds(int, (i for i in range(10)))  # value type not supported by Hydra
+    hydra_zen.errors.HydraZenUnsupportedPrimitiveError: Building: int ..
+
+
     .. _meta-field:
 
     **Using meta-fields**
@@ -978,7 +982,7 @@ def builds(
 
     Let's use a wrapper to add a unit-conversion step to a config. We'll modify a
     config that builds a function, which converts a temperature in Farenheit to
-    Celcius, and add a wrapper it so that it will convert from Farenheit to Kelvin
+    Celcius, and add a wrapper to it so that it will convert from Farenheit to Kelvin
     instead.
 
     >>> def faren_to_celsius(temp_f):  # our target