Docs Suggestion: Example section introductions

[tylerflex]

Kind of a minor comment but I think it will improve the docs a bit.

For each of our docs sections, there is a page with a bunch of links to the specific notebooks. For example, in the "design space exploration" section, it looks like this

https://docs.flexcompute.com/projects/tidy3d/en/v2.6.0rc1/notebooks/docs/features/parameter_sweep.html

I think what would improve things a bit is to put a few paragraphs of introduction on this page, explaining what these examples are showing and which ones might be best to check out depending on what you want to do. For example, this page could include some text above the example links like:

" Tidy3D offers a few tools that facilitate and automate the exploration of a user-defined design space. The design plugin is a wrapper that allows users to define a general "parameter space" and sample this space through tidy3d simulations. The result is returned to the user in a pandas.DataFrame format for easy post processing and analysis. For a detailed tutorial, see [Design Plugin Tutorial Link]. We also have tools for batch processing of simulations, which can make custom parameter sweeps convenient. For an example of batching simulations and other tools for managing the results in a more custom way, see the [Parameter Sweep Tutorial Link] example. "

we can also address a few other improvements here, such as describing the limitations of the various features, or linking to the feature README.md for more information.

[tomflexcompute]

Yeah sounds like a great idea. Can prepare the paragraphs for each section and then @daquinteroflex can incoperate them into the page

[tylerflex]

I think they can be written into these pages, but dario can comment.

[daquinteroflex]

Hmm let me have a think how best to do this as it might require a custom toctree, but we can go preparing the paragrahs anyway for sure (maybe this will solve the multiple style header issue you both suggested too)

[tomflexcompute]

I drafted some intro paragraphs for the case studies. @tylerflex @daquinteroflex feel free to take a look here and provide any edits as you see fit. After you think the texts look good, we can implement it and see how it looks. Then we can do the same for the Python tutorial sections.

[tylerflex]

Thanks @tomflexcompute these look really good. Would it be useful for me to do a few? such as the design space exploration and adjoint?

As a micro-optimization: I think in general the more links we can put throughout the docs, the better, so whenever we reference an example or other section we can add a link, but just the text for now will give us a big improvement I think.

[tomflexcompute]

Yeah absolutely. If you can write a few, please add them to the notion page. I'll continue adding paragraphs for the python tutorial sections as well in the upcoming week.

For the adjoint examples, I think we briefly thought about moving them to the case study and creating a new category. Not sure if we want to have them in the Photonic Design Optimization section or have a separate section like Adjoint Optimization and change the current Photonic Design Optimization to something like Gradient-free Optimization?

For the migration, I'll just need to create the thumbnail images. Otherwise should be straightforward.

[tylerflex]

I added a few sections.

I'd say we could either have (1) A) Optimization (adjoint + global optimization) B) Design Space Exploration (sweep/batch)

or (2) just separate inverse design out: A) Inverse design (adjoint only) B) Design Space Exploration (sweep/batch + global optimization)

Which do you think makes more sense? I'm maybe more in favor of the 2nd but only slightly, only because we have almost 15 adjoint examples so far.

[tomflexcompute]

Thanks Tyler. I think either way works. The first approach is slightly more convenient as we only need to move the adjoint examples from tutorials to case studies. In approach 2, we will move the sweep and batch notebooks to case studies? They are more like tutorials than case studies but could be fine as well.

[tylerflex]

I'm not really sure, maybe I'll leave it up to you to decide. I dont have any strong preferences.

Side note: we should consider I think renaming the "FDTD Adjoint Optimization" header to maybe "Inverse Design Optimization" or something. I dont know if people know Adjoint optimization?

[tomflexcompute]

Yeah that's a good point. I think including "FDTD" was Zongfu's original idea to optimize SEO for the "FDTD" keyword. Should be fine to remove it. I'll made some thumbnails and have a PR probably at some point next week to reorganize the sections and we can see which arrangement makes more sense then.