docs(config): docs for new config system FXC-3945

docs/_ext/custom-robots.py

@@ -6,18 +6,13 @@
 def process_robots_txt(app, exception):
     # Get the path to the robots.txt file
     robots_file = os.path.join(app.outdir, "robots.txt")
-
-    # Read the contents of the robots.txt file
     with open(robots_file) as f:
         contents = f.read()
 
-    # Modify the contents as needed
-    # site_map = app.config['html_baseurl'] + app.config['version'] + app.config['language'] + 'sitemap.xml'
     site_map = "/".join(
         [app.config["html_baseurl"], app.config["language"], app.config["version"], "sitemap.xml"]
     ).replace("//", "/")
-    new_content = f"\nSitemap: {site_map}"
-    contents += new_content
+    contents += f"\nSitemap: {site_map}"
 
     # Update the robots.txt file with the modified contents
     with open(robots_file, "w") as f:

docs/_templates/module.rst

@@ -39,4 +39,5 @@
 
    .. rubric:: Inherited Common Usage
 
-   .. include:: ../_custom_autosummary/{{ fullname }}.rst
+   .. include:: ../_custom_autosummary/{{ fullname }}.rst
+      :optional:

docs/api/configuration.rst

@@ -0,0 +1,41 @@
+Configuration API
+=================
+
+.. currentmodule:: tidy3d.config
+
+The objects and helpers below expose the public configuration interface.
+
+Manager and Helpers
+-------------------
+
+.. autosummary::
+   :toctree: _autosummary/
+   :template: module.rst
+
+   tidy3d.config.ConfigManager
+   tidy3d.config.get_manager
+   tidy3d.config.reload_config
+
+Legacy Compatibility
+--------------------
+
+.. autosummary::
+   :toctree: _autosummary/
+   :template: module.rst
+
+   tidy3d.config.LegacyConfigWrapper
+   tidy3d.config.Environment
+   tidy3d.config.EnvironmentConfig
+
+Registration Utilities
+----------------------
+
+.. autosummary::
+   :toctree: _autosummary/
+   :template: module.rst
+
+   tidy3d.config.register_section
+   tidy3d.config.register_plugin
+   tidy3d.config.register_handler
+   tidy3d.config.get_sections
+   tidy3d.config.get_handlers

docs/api/constants.rst

@@ -35,7 +35,7 @@ Tidy3D Configuration
    :toctree: _autosummary/
    :template: module.rst
 
-   tidy3d.config.Tidy3dConfig
+   tidy3d.config.ConfigManager
 
 Default Absorber Parameters
 ----------------------------
@@ -92,4 +92,4 @@ Precision & Comparator Values
    tidy3d.constants.fp_eps
    tidy3d.constants.pec_val
    tidy3d.constants.LARGE_NUMBER
-   tidy3d.constants.GLANCING_CUTOFF
+   tidy3d.constants.GLANCING_CUTOFF

docs/api/index.rst

@@ -18,6 +18,7 @@ API |:computer:|
     output_data
     analytic_beams
     utilities
+    configuration
     mesh/index
     heat/index
     charge/index

docs/api/simulation.rst

@@ -61,7 +61,8 @@ Logging
    :toctree: _autosummary/
    :template: module.rst
 
-   tidy3d.config.logging_level
-   tidy3d.set_logging_file
+   tidy3d.log.set_logging_level
+   tidy3d.log.set_log_suppression
+   tidy3d.log.set_logging_file
 
 ~~~~

docs/api/sources.rst

@@ -6,7 +6,7 @@ Sources
 Overview
 --------
 
-Sources in Tidy3D provide the necessary excitation to investigate the EM behaviour of the structures under simulation. The type of source used in a simulation tends to be very application-specific. For instance, a ``PlaneWave`` source may be used for a unit cell simulation in a metalens; whereas a ``ModeSource`` would be more appropriate for a waveguide crossing problem.
+Sources in Tidy3D provide the necessary excitation to investigate the EM behavior of the structures under simulation. The type of source used in a simulation tends to be very application-specific. For instance, a ``PlaneWave`` source may be used for a unit cell simulation in a metalens; whereas a ``ModeSource`` would be more appropriate for a waveguide crossing problem.
 
 A generic source can be thought of as composed of two parts: a spatial profile and a temporal profile. The former dictates the field distribution in space, whereas the latter determines the frequency band covered by the source, and by extension, the overall simulation.
 

docs/configuration/index.rst

@@ -0,0 +1,156 @@
+Configuration Guide |:gear:|
+============================
+
+.. highlight:: python
+
+Working with cloud simulations usually requires a handful of settings such as
+your API key, the active environment, and any local tweaks you make while
+experimenting. The ``config`` object (available via ``from tidy3d import config``)
+keeps all of this in one place through a single interface. This page explains
+how it behaves, where values are stored, and how to keep your changes
+consistent across sessions. For a catalog of every option, see :doc:`reference`.
+
+Getting Started
+---------------
+
+Most users only need the following import::
+
+    from tidy3d import config
+
+You can then read or update sections just like attributes::
+
+    # read values
+    print(config.web.api_endpoint)
+    print(config.logging.level)
+
+    # update values
+    config.logging.level = "DEBUG"
+    config.web.timeout = 60
+    config.save()
+
+The ``save()`` call writes your edits to disk so the same settings load the
+next time you import ``tidy3d``.
+
+Where Settings Are Stored
+-------------------------
+
+Tidy3D chooses a configuration directory the first time you import the module.
+The location depends on your operating system:
+
+.. list-table:: Default configuration directory
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Platform
+     - Path
+   * - macOS / Linux
+     - ``~/.config/tidy3d``
+   * - Windows
+     - ``C:\Users\<you>\.config\tidy3d``
+
+You can override this by setting the ``TIDY3D_BASE_DIR`` environment variable
+*before* importing ``tidy3d``. When it is present, the config files are kept in
+``<base>/.tidy3d``. If the chosen location is not writable, Tidy3D falls back to
+a temporary directory and warns that the settings will not persist.
+
+Files Inside the Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``config.toml`` – base settings shared by all profiles.
+- ``profiles/<name>.toml`` – optional overrides for custom profiles. Each file
+  only contains the differences from the base settings.
+
+Priority Order
+--------------
+
+Whenever you read ``config.<section>.<field>``, the value comes from the highest
+priority source in the list below. Lower entries only apply when the ones above
+them do not set a value.
+
+1. Runtime changes you make in the current Python session.
+2. Environment variables (``TIDY3D_<SECTION>__<FIELD>``).
+3. Profile overrides from ``profiles/<name>.toml``.
+4. The base ``config.toml`` file.
+5. Built-in profiles (for example ``prod`` and ``dev``) bundled with Tidy3D.
+6. Default values defined by the software.
+
+This means environment variables always win over ``config.toml``, and any
+attribute you set in code wins over everything else until you discard it or
+call ``save()``.
+
+Making Changes That Last
+------------------------
+
+Runtime Updates
+~~~~~~~~~~~~~~~
+
+Assignments like ``config.logging.level = "INFO"`` apply immediately but only
+live in memory. They affect new simulations started in the same interpreter but
+disappear when the process exits.
+
+Saving to Disk
+~~~~~~~~~~~~~~
+
+Call ``config.save()`` to write the current profile to disk. The method removes
+environment-variable overrides automatically so you never persist an API key or
+other secret that was loaded from the shell. To store the full set of values,
+including defaults, pass ``include_defaults=True``::
+
+    config.save(include_defaults=True)
+
+Profiles
+--------
+
+Tidy3D ships with built-in profiles such as ``prod`` and ``dev``. Switch between
+them with::
+
+    config.switch_profile("dev")
+
+To create your own profile, switch to a new name, edit settings, then call
+``save()``::
+
+    config.switch_profile("my_profile")
+    config.web.api_endpoint = "https://example.com"
+    config.save()
+
+This writes ``profiles/my_profile.toml`` containing only the adjustments you
+made. Use ``config.profiles.list()`` to discover available built-in and user
+profiles.
+
+Environment Variables
+---------------------
+
+Environment variables let you override individual options without touching any
+files. The naming pattern is ``TIDY3D_<SECTION>__<FIELD>``, for example::
+
+    export TIDY3D_LOGGING__LEVEL=WARNING
+
+Supported variables take effect the next time you import ``tidy3d``. Remove a
+variable or clear the shell environment to restore the lower priority setting.
+
+Command Line Helpers
+--------------------
+
+Use ``tidy3d configure`` to store your API key in ``config.toml``. The command
+creates the directory if it is missing and updates only the ``web`` section.
+
+If you have older files in ``~/.tidy3d``, run ``tidy3d config migrate`` to move
+them into the new location described above. The command copies the legacy files
+into the canonical directory, leaving the originals untouched unless you pass
+``--delete-legacy``. Use ``--overwrite`` if you have already started using the
+new location and want to replace those files with the legacy versions.
+
+Legacy Access Points
+--------------------
+
+Older code paths such as ``tidy3d.config.logging_level`` and ``tidy3d.config.Env``
+still work. They emit a ``DeprecationWarning`` each time you use them to help
+you transition to the modern interface. See :doc:`migration` for advice on
+updating scripts that depend on these names.
+
+Next Steps
+----------
+
+- :doc:`reference`
+- :doc:`migration`
+- :doc:`../api/configuration`

docs/configuration/migration.rst

@@ -0,0 +1,31 @@
+Upgrading Existing Setups
+=========================
+
+This short note highlights the differences you may notice when moving from
+earlier versions of Tidy3D to the current configuration manager.
+
+File Locations
+--------------
+
+- Previous releases stored settings in ``~/.tidy3d`` on all platforms. The new
+  manager now prefers the platform-specific paths described in
+  :doc:`index`.
+- Your existing ``~/.tidy3d/config`` is still respected. Run
+  ``tidy3d config migrate`` if you would like to copy it into the new directory.
+  Append ``--overwrite`` to replace any files that already exist in the new
+  location, and ``--delete-legacy`` to remove ``~/.tidy3d`` after the copy.
+
+Environment Switching
+---------------------
+
+- The ``Env`` helper remains available. Calls such as ``Env.dev.active()`` now
+  forward to the new manager and produce a ``DeprecationWarning`` to encourage
+  the modern API, e.g. ``config.switch_profile("dev")``.
+
+Legacy Attributes
+-----------------
+
+- Shorthand properties ``config.logging_level``, ``config.log_suppression``,
+  and ``config.use_local_subpixel`` still work and set the equivalent fields in
+  ``config.logging`` or ``config.simulation``. Each call raises a warning so
+  you can update scripts at your own pace.