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

[yaugenst-flex]

I split out the docs changes from #2711 to make the diff a bit more manageable.

Greptile Overview

Updated On: 2025-10-22 07:38:00 UTC

Greptile Summary

This PR adds comprehensive documentation for the new unified configuration system in Tidy3D. The changes introduce a dedicated configuration section covering the new tidy3d.config.config object, platform-specific file locations, priority rules, profile management, and migration guidance from the legacy ~/.tidy3d/config approach. The documentation updates span multiple files: a new configuration guide at docs/configuration/index.rst, a migration guide at docs/configuration/migration.rst, new API reference at docs/api/configuration.rst, and refactored references in docs/index.rst, docs/install.rst, and docs/extras/index.rst. These changes support a broader configuration system refactoring (split from PR #2711) that moves from a class-based Tidy3dConfig to a module-level config object, adopts platform-appropriate config directories (like ~/.config/tidy3d on Linux/macOS and %APPDATA%\\tidy3d on Windows), and introduces profile-based configuration management. The documentation maintains backward compatibility guidance for the deprecated Env helper while encouraging migration to the new API.

Important Files Changed

Changed Files

Filename	Score	Overview
docs/configuration/index.rst	5/5	New comprehensive guide documenting config object usage, file locations, priority rules, profiles, and CLI commands
docs/configuration/migration.rst	5/5	New migration guide explaining transition from legacy ~/.tidy3d to new platform-specific config system
docs/api/configuration.rst	5/5	New API reference page documenting ConfigManager, legacy wrappers, and registration utilities
docs/index.rst	5/5	Refactored main page to reference centralized config docs, removing redundant manual setup instructions
docs/install.rst	5/5	Updated API key configuration section to reference new config documentation instead of hardcoded paths
docs/api/constants.rst	5/5	Updated reference from Tidy3dConfig class to config object, plus formatting fix
docs/api/index.rst	5/5	Added configuration section to API documentation table of contents
docs/extras/index.rst	5/5	Added cross-reference to new configuration documentation for discoverability

Confidence score: 5/5

• This PR is safe to merge with minimal risk as it contains only documentation changes with no runtime code modifications
• All files are properly formatted RST documentation with clear structure, accurate cross-references, and practical examples that align with the established project conventions
• No files require special attention - this is a documentation-only change that improves user guidance for the new configuration system

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI/Command Line
    participant ConfigAPI as Configuration API
    participant ConfigFiles as Config Files (TOML)
    participant EnvVars as Environment Variables
    participant Manager as ConfigManager
    participant Docs as Documentation System
    
    User->>CLI: "tidy3d configure --apikey=XXX"
    CLI->>ConfigAPI: configure(apikey)
    ConfigAPI->>Manager: get_manager()
    Manager->>ConfigFiles: Check ~/.config/tidy3d/config.toml
    ConfigFiles-->>Manager: Load existing config
    Manager->>ConfigFiles: Write web.api_key
    ConfigFiles-->>Manager: Confirm save
    Manager-->>ConfigAPI: Configuration saved
    ConfigAPI-->>CLI: Success message
    CLI-->>User: "Configuration complete"
    
    User->>User: "import tidy3d as td"
    User->>ConfigAPI: "from tidy3d.config import config"
    ConfigAPI->>Manager: Initialize manager
    Manager->>EnvVars: Check TIDY3D_* variables
    EnvVars-->>Manager: Return overrides
    Manager->>ConfigFiles: Read config.toml
    ConfigFiles-->>Manager: Return base settings
    Manager->>ConfigFiles: Read profiles/<name>.toml
    ConfigFiles-->>Manager: Return profile overrides
    Manager->>Manager: Merge settings (priority order)
    Manager-->>ConfigAPI: Return unified config
    
    User->>ConfigAPI: "config.logging.level = 'DEBUG'"
    ConfigAPI->>Manager: Update runtime value
    Manager-->>ConfigAPI: Value updated
    
    User->>ConfigAPI: "config.save()"
    ConfigAPI->>Manager: save()
    Manager->>Manager: Strip env var overrides
    Manager->>ConfigFiles: Write profiles/<name>.toml
    ConfigFiles-->>Manager: Confirm write
    Manager-->>ConfigAPI: Save complete
    ConfigAPI-->>User: "Settings persisted"
    
    User->>ConfigAPI: "config.switch_profile('dev')"
    ConfigAPI->>Manager: switch_profile('dev')
    Manager->>ConfigFiles: Load profiles/dev.toml
    ConfigFiles-->>Manager: Return dev settings
    Manager->>Manager: Apply profile settings
    Manager-->>ConfigAPI: Profile switched
    ConfigAPI-->>User: "Using 'dev' profile"
    
    User->>CLI: "tidy3d config migrate"
    CLI->>Manager: migrate_legacy_config()
    Manager->>ConfigFiles: Check ~/.tidy3d/config.toml
    ConfigFiles-->>Manager: Return legacy config
    Manager->>ConfigFiles: Copy to ~/.config/tidy3d/
    ConfigFiles-->>Manager: Migration complete
    Manager-->>CLI: Success
    CLI-->>User: "Migration complete"
    
    Docs->>ConfigAPI: Import configuration docs
    ConfigAPI-->>Docs: "Provide API reference"
    Docs->>Docs: Generate Sphinx documentation
    Docs-->>User: "Render docs/configuration/index.rst"

Loading

[greptile-apps]

_{8 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[github-actions]

Diff Coverage

Diff: origin/develop...HEAD, staged and unstaged changes

No lines with coverage information in this diff.

[FilipeFcp]

Hi @yaugenst-flex

The "Configuration API" rendered like this here:

Is just it?

All the rest seems great!

[yaugenst-flex]

Hey @FilipeFcp thanks for having a look! I'm not sure, did you fully build the docs? These sections are not empty in the rst but they contain _autosummary stubs for the relevant APIs, so I think the page is only empty if the docs haven't been fully built?

[daquinteroflex]

Docs will be https://docs.flexcompute.com/projects/tidy3d/en/yaugenst-flex-config-docs/ as soon as it finishes building

[yaugenst-flex]

Added a couple of pages and made sure everything renders correctly.

[yaugenst-flex]