Improving API docs

[yuanshen-flexcompute]

Adding summary pages for each major section in the API docs. Also did some re-arrangement for better readability and user access.

Greptile Summary

This PR represents a comprehensive overhaul of the Tidy3D API documentation structure, transforming it from basic auto-generated reference pages into user-friendly, educational guides. The changes add detailed overview sections, practical code examples, and logical reorganization across multiple documentation files.

Key improvements include:

• Enhanced structure: Files like sources.rst, mediums.rst, monitors.rst, and geometry.rst now include comprehensive overview sections that explain concepts before diving into API details
• Better organization: Content is grouped into logical categories (e.g., monitors organized by Field, Flux, Mode, etc.) rather than alphabetical listings
• Practical examples: Code snippets and visual diagrams (new image assets) help users understand implementation patterns
• Consolidation: Related functionality is grouped together - field projector content moved to monitors, subpixel averaging moved to discretization, and Structure/Scene combined into a single page
• Navigation improvements: The main API index now serves as a navigation hub rather than a single overwhelming page
• Cross-references: Links to tutorials, notebooks, and learning materials provide pathways for deeper understanding

The restructuring follows modern documentation best practices by emphasizing user experience and progressive disclosure over pure API enumeration. Files are organized to match typical user workflows, starting with basic concepts and progressing to advanced features. The changes maintain all original API references while significantly enhancing discoverability and educational value.

Important Files Changed

File Changes Summary

Filename	Score	Overview
docs/api/abstract_models.rst	1/5	Contains extensive duplicate entries in autosummary that will cause documentation build issues
docs/api/subpixel_averaging.rst	2/5	Completely emptied but file still exists, creating potential broken links and build problems
docs/api/monitors.rst	2/5	Major enhancement with comprehensive categorization but contains critical syntax error (missing quote)
docs/api/abstract_base.rst	4/5	Minor improvements to title and description with potential duplicate entry issue
docs/api/geometry.rst	4/5	Comprehensive restructuring with excellent educational content but has undefined variable references
docs/api/boundary_conditions.rst	5/5	Excellent restructuring from basic list to comprehensive guide with mathematical formulations and examples
docs/api/discretization.rst	5/5	Transformed into educational guide with clear organization and extensive cross-references
docs/api/field_projector.rst	5/5	Successfully consolidated into monitors.rst for better logical organization
docs/api/index.rst	5/5	Improved navigation structure by removing inline content and reorganizing section order
docs/api/mediums.rst	5/5	Major restructuring with comprehensive categorization, examples, and cross-references
docs/api/output_data.rst	5/5	Well-structured reorganization with clear sections and comprehensive API coverage
docs/api/scene.rst	5/5	Successfully consolidated into structure_and_scene.rst for better user experience
docs/api/simulation.rst	5/5	Expanded from basic reference to comprehensive simulation workflow documentation
docs/api/sources.rst	5/5	Excellent transformation from bare API list to educational guide with practical examples
docs/api/structure_and_scene.rst	5/5	New consolidated documentation page with clear examples and cross-references
docs/api/structures.rst	5/5	Successfully removed as part of logical consolidation into other files
docs/api/submit_simulations.rst	5/5	Minor formatting improvement with proper file termination

Confidence score: 2/5

• This PR contains several critical issues that will prevent documentation from building correctly
• Score lowered due to syntax errors, duplicate entries, and empty files that will cause build failures
• Pay close attention to abstract_models.rst (extensive duplicates), monitors.rst (syntax error), and subpixel_averaging.rst (empty file)

[greptile-apps]

_{17 files reviewed, 9 comments}

_{Edit Code Review Bot Settings | Greptile}

[github-actions]

Diff Coverage

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

No lines with coverage information in this diff.

[daquinteroflex]

Just making some notes for myself of things that I'm fixing:

• https://docs.flexcompute.com/projects/tidy3d/en/demo-test-docs_api/api/index.html

[daquinteroflex]

This PR is great @yuanshen-flexcompute . I've made a few comments but maybe it's easier to quickly sync when you can early today to agree a bit on structural decisions

[daquinteroflex]

Gonna be another PR

[daquinteroflex]

I'll close this now?