FEAT: Docs upgrades throughout 📈

docs/_static/css/custom.css

@@ -32,12 +32,14 @@ iframe {width: 100%;border: unset}
 html[data-theme="light"] {
     --pst-color-primary: #b5445b;
     --pst-color-secondary: #4772ae;
+    --tab-color: var(--pst-color-secondary);
     --pst-color-link: var(--pst-color-muted);
 }
 
 html[data-theme="dark"] {
     --pst-color-primary: #4772ae;
     --pst-color-secondary: #b5445b;
+    --tab-color: #9647AE; /*#1C2E46;*/
     --pst-color-link: var(--pst-color-muted);
     --sd-color-info-bg:  var(--pst-color-primary);
 }
@@ -65,7 +67,7 @@ img {
 }
 
 .sphinx-tabs-tab {
-    background: var(--pst-color-secondary);
+    background: var(--tab-color);
     padding: 0.5em;
     padding-right: 2em;
     padding-left: 2em;

docs/changelog.rst

@@ -2,4 +2,24 @@
 Changelog |:rewind:|
 ********************
 
+Documentation Versions
+######################
+
+You can find the documentation for all the supported versions of ``tidy3d`` within this website.
+To switch between versions, use the version selector in the bottom left corner of the page as per the image below.
+The version selector is only available on the main page of the documentation.
+
+.. image:: ./_static/img/documentation_versions.png
+   :width: 50%
+   :alt: Version Selector
+
+After version ``>=2.6``, the documentation was restructured so old internal documentation links will not match to the
+new internal documentation page links. To access the new documentation, we recommend navigating to the `main page <../>`_ and switching versions from there before navigating to the page.
+
+
+
+Version Release Notes
+#######################
+
 .. include:: ../CHANGELOG.md
+   :parser: myst_parser.sphinx_

docs/index.rst

@@ -1,5 +1,6 @@
+******************************
 Tidy3D Electromagnetic Solver
-=============================
+******************************
 
 .. role:: raw-html(raw)
     :format: html
@@ -13,44 +14,88 @@ Tidy3D Electromagnetic Solver
 .. image:: https://img.shields.io/github/actions/workflow/status/flexcompute/tidy3d/run_tests.yml?style=for-the-badge
 .. image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/daquinteroflex/4702549574741e87deaadba436218ebd/raw/tidy3d_extension.json
 .. image:: https://img.shields.io/github/license/flexcompute/tidy3d?style=for-the-badge
-.. image:: https://img.shields.io/badge/Demo-Notebooks-8A2BE2?style=for-the-badge
+.. image:: https://img.shields.io/badge/Demo-Notebooks-9647AE?style=for-the-badge
     :target: https://github.com/flexcompute/tidy3d-notebooks
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
    :target: https://github.com/psf/black
 
 
-.. To do items:
-.. * open simple example in colab with API saved as environment variable and `!pip install tidy3d` in the first line.
-.. * toggle between command line - notebook / python instructions in section 1
 Tidy3D is a software package for solving extremely large electrodynamics problems using the finite-difference time-domain (FDTD) method. It can be controlled through either an `open source python package <https://github.com/flexcompute/tidy3d>`_ or a `web-based graphical user interface <https://tidy3d.simulation.cloud>`_.
 
-If you’d rather skip installation and run an example in one of our web-hosted notebooks, `click here <https://tidy3d.simulation.cloud/notebook?file=StartHere.ipynb>`_.
+Get Started
+===========
 
-.. `TODO: open example in colab <https://github.com/flexcompute/tidy3d>`_
+.. tabs::
+
+    .. group-tab:: Install on Linux |:penguin:| & MacOS |:apple:|
+
+        Install the latest stable python library `tidy3d <https://github.com/flexcompute/tidy3d>`_ for creating, managing, and postprocessing simulations with
+
+        .. code-block:: bash
+
+            pip install --user tidy3d
+
+        Next, configure your ``tidy3d`` package with the API key from your account.
+
+        `Get your free API key <https://tidy3d.simulation.cloud/account?tab=apikey>`_
+
+        .. code-block:: bash
+
+           tidy3d configure --apikey=XXX
+
+        And enter your API key when prompted.
+
+        For more detailed installation instructions, see `this page <./install.html>`_.
+
+    .. group-tab:: Install on Windows |:window:|
+
+        Install the latest stable python library `tidy3d <https://github.com/flexcompute/tidy3d>`_ for creating, managing, and postprocessing simulations in your virtual environment with:
+
+        .. code-block:: bash
+
+            pip install --user tidy3d
+
+        Next, configure your ``tidy3d`` package with the API key from your account.
+
+        `Get your free API key <https://tidy3d.simulation.cloud/account?tab=apikey>`_
+
+        To automatically configure the API key, you will need to install the following extra packages:
 
-1. Set up Tidy3D
-~~~~~~~~~~~~~~~~
+        .. code-block:: bash
 
-Install the python library `tidy3d <https://github.com/flexcompute/tidy3d>`_ for creating, managing, and postprocessing simulations with
+            pip install pipx
+            pipx run tidy3d configure --apikey=XXX
 
-.. code:: bash
+        If you're running into trouble, you may need to manually set the API key directly in the configuration file where Tidy3D looks for it.
+        You need to place the ``$HOME/.tidy3d/config`` file in your home directory such as ``C:\Users\username\`` (where ``username`` is your username).
 
-    pip install tidy3d
+        The API key must be in a file called ``$HOME/.tidy3d/config`` located in your home directory, with the following contents
 
-Next, configure your ``tidy3d`` package with the API key from your account.
+        .. code-block:: bash
 
-`Get your free API key <https://tidy3d.simulation.cloud/account?tab=apikey>`_
+            apikey = "XXX"
 
-.. code-block:: bash
+        You can manually set up your file like this, or do it through the command line line:
 
-   tidy3d configure
+        .. code-block:: bash
 
-And enter your API key when prompted.
+            echo 'apikey = "XXX"' > ~/.tidy3d/config
 
-For more detailed installation instructions, see `this page <https://docs.flexcompute.com/projects/tidy3d/en/latest/install.html>`_.
+        Note the quotes around `XXX`.
 
-2. Run a Simulation
-~~~~~~~~~~~~~~~~~~~
+    .. group-tab:: In the Cloud |:cloud:|
+
+        If you’d rather skip installation and run an example in one of our web-hosted notebooks, `click here <https://tidy3d.simulation.cloud/notebook?file=StartHere.ipynb>`_.
+
+
+
+.. To do items:
+.. * open simple example in colab with API saved as environment variable and `!pip install tidy3d` in the first line.
+.. * toggle between command line - notebook / python instructions in section 1
+
+
+Quick Example
+=============
 
 Start running simulations with just a few lines of code. Run this sample code to simulate a 3D dielectric box in Tidy3D and plot the corresponding field pattern.
 
@@ -69,7 +114,7 @@ Start running simulations with just a few lines of code. Run this sample code to
 
    # create structure - a box centered at 0, 0, 0 with a size of 1.5 micron and permittivity of 2
    square = td.Structure(
-       geometry=td.Box(center=(0, 0, 0), size=(1.5, 1.5, 1.5)), 
+       geometry=td.Box(center=(0, 0, 0), size=(1.5, 1.5, 1.5)),
        medium=td.Medium(permittivity=2.0)
    )
 
@@ -104,20 +149,22 @@ Start running simulations with just a few lines of code. Run this sample code to
    data = td.web.run(sim, task_name="quickstart", path="data/data.hdf5", verbose=True)
    ax = data.plot_field("fields", "Ey", z=0)
 
+
+
 This will produce the following plot, which visualizes the electromagnetic fields on the central plane.
 
 .. image:: _static/quickstart_fields.png
    :width: 1200
 
-3. Analyze Results
-~~~~~~~~~~~~~~~~~~
-
 a) Postprocess simulation data using the same python session, or
 
 b) View the results of this simulation on our web-based `graphical user interface <https://tidy3d.simulation.cloud>`_.
 
-4. Learn More
-~~~~~~~~~~~~~
+.. `TODO: open example in colab <https://github.com/flexcompute/tidy3d>`_
+
+
+Further Information
+====================
 
 .. toctree::
   :maxdepth: 2
@@ -131,4 +178,24 @@ b) View the results of this simulation on our web-based `graphical user interfac
   changelog
   About our Solver <https://www.flexcompute.com/tidy3d/solver/>
 
+Github Repositories
+~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Repository
+   * - Source Code
+     - https://github.com/flexcompute/tidy3d
+   * - Example Notebooks
+     - https://github.com/flexcompute/tidy3d-notebooks
+   * - FAQ Source Code
+     - https://github.com/flexcompute/tidy3d-faq
+
+These repositories are the a very good way to interact with the relevant tool developers.
+We encourage you to ask questions or request features through the "Discussions" or "Issues" tabs of each repository accordingly.
+
+
+