From 32e82d3d5ff2eebb7c55b1ba36ec084723f9f685 Mon Sep 17 00:00:00 2001
From: Olivier Delalleau <507137+odelalleau@users.noreply.github.com>
Date: Thu, 7 Oct 2021 16:07:44 -0400
Subject: [PATCH] Refactor titles of the structured configs documentation
 (#790)

The objective is to make it easier to understand that all content in the
`structured_config.rst` file is related to structured configs, when
looking at the left navigation pane. More precisely, the main changes
are that:

- The "Lists" and "Dicts" sections are now moved inside the "Structured
  configs" main section (getting rid of the intermediate "Containers"
  section to reduce nesting)
- The "Misc" section is also moved inside the "Structured Configs" main
  section (and is also renamed to give a better idea of what's inside
  it, now that its detailed content isn't shown anymore in the left
  navigation pane)
- Finally the "Merging with other configs" section is also moved inside
  the "Structured Configs" main section so as to make it clear that it
  is related to structured configs.
---
 docs/source/structured_config.rst | 27 +++++++++++----------------
 1 file changed, 11 insertions(+), 16 deletions(-)

diff --git a/docs/source/structured_config.rst b/docs/source/structured_config.rst
index 516337222..11806a996 100644
--- a/docs/source/structured_config.rst
+++ b/docs/source/structured_config.rst
@@ -1,4 +1,4 @@
-.. _structured_config:
+.. _structured_configs:
 
 .. testsetup:: *
 
@@ -11,8 +11,8 @@
     import sys
     os.environ['USER'] = 'omry'
 
-Structured config
------------------
+Structured configs
+------------------
 Structured configs are used to create OmegaConf configuration object with runtime type safety.
 In addition, they can be used with tools like mypy or your IDE for static type checking.
 
@@ -199,11 +199,6 @@ You can assign subclasses:
     >>> assert conf.manager.duper == True
 
 
-Containers
-----------
-
-Python container types are fully supported in Structured configs.
-
 Lists
 ^^^^^
 Structured Config fields annotated with ``typing.List`` or ``typing.Tuple`` can hold any type
@@ -275,8 +270,8 @@ Like with Lists, the types of values contained in Dicts are verified at runtime.
     >>> with raises(ValidationError):
     ...     conf.users["Joe"] = 10
 
-Misc
-----
+Other special features
+^^^^^^^^^^^^^^^^^^^^^^
 OmegaConf supports field modifiers such as ``MISSING`` and ``Optional``.
 
 .. doctest::
@@ -293,7 +288,7 @@ OmegaConf supports field modifiers such as ``MISSING`` and ``Optional``.
     >>> conf: Modifiers = OmegaConf.structured(Modifiers)
 
 Mandatory missing values
-^^^^^^^^^^^^^^^^^^^^^^^^
+++++++++++++++++++++++++
 
 Fields assigned the constant ``MISSING`` do not have a value and the value must be set prior to accessing the field.
 Otherwise a ``MissingMandatoryValue`` exception is raised.
@@ -307,7 +302,7 @@ Otherwise a ``MissingMandatoryValue`` exception is raised.
 
 
 Optional fields
-^^^^^^^^^^^^^^^
++++++++++++++++
 
 .. doctest::
 
@@ -321,7 +316,7 @@ Optional fields
 
 
 Interpolations
-^^^^^^^^^^^^^^
+++++++++++++++
 
 :ref:`interpolation` works normally with Structured configs, but static type checkers may object to you assigning a string to another type.
 To work around this, use the special functions ``omegaconf.SI`` and ``omegaconf.II`` described below.
@@ -380,8 +375,8 @@ Note however that this validation step is currently skipped for container node i
     >>> assert cfg.some_dict == 0  # type mismatch, but no error
 
 
-Frozen
-^^^^^^
+Frozen classes
+++++++++++++++
 
 Frozen dataclasses and attr classes are supported via OmegaConf :ref:`read-only-flag`, which makes the entire config node and all if it's child nodes read-only.
 
@@ -404,7 +399,7 @@ The read-only flag is recursive:
     ...    conf.list[0] = 20
 
 Merging with other configs
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once an OmegaConf object is created, it can be merged with others regardless of its source.
 OmegaConf configs created from Structured configs contains type information that is enforced at runtime.