diataxis (#3219)

* diataxis

* Move docs to appropriate folders

Co-authored-by: Deeksha <[email protected]>

* Enhanced glossary

* Fix typo that breaks codespell

* Remove dead link AI added

* Remove tutorial references from how-to page

* More glossary adds

* Reorg and rename

* Index reorgs and biblio rename

* Fix internal docs links and some underlinds

Co-authored-by: Deeksha <[email protected]>
Co-authored-by: Anirban <[email protected]>

* Fixes some more docs errors

* Simplify the main index

* Remove automatically generated files from PR

* Ignore autogenerated files

* Josh's glossary updates

Co-authored-by: Joshua Shields <[email protected]>

* Improve analyzing TARDIS output page

---------

Co-authored-by: Andrew Fullard <[email protected]>
Co-authored-by: Deeksha <[email protected]>
Co-authored-by: Anirban <[email protected]>
Co-authored-by: Joshua Shields <[email protected]>

Author: 5 people

.gitignore

@@ -86,3 +86,6 @@ benchmarks/data/*.h5
 .asv/
 pkgs/
 release_hashes.txt
+docs/how_to_guides.rst
+docs/workflows.rst
+docs/analyzing_tardis/spectrum/tardis_example.yml

docs/analyzing_tardis/index.rst

@@ -1,12 +1,24 @@
-*******************************
-Analyzing TARDIS
-*******************************
+************************************
+Analyszing TARDIS Simulation Outputs
+************************************
 
-This section provides an overview of how to analyze the outputs generated by TARDIS.
+This section provides practical solutions for common analysis tasks. These guides assume you have completed simulations and want to extract scientific insights from the results.
+
+Quick Reference
+===============
+
+* :doc:`spectrum/index` - Analyzing and visualizing spectra
+* :doc:`visualization/index` - Creating plots and visualizations
+
+Detailed Guides
+================
 
 .. toctree::
     :maxdepth: 2
-    :hidden:
 
-    analyzing_tardis/spectrum/spectrum-visualization-notebook
+    spectrum/spectrum-visualization-notebook
+    visualization/index
+
+.. note::
+   **Need technical details?** Check the API reference for analysis modules.
 

docs/analyzing_tardis/visualization/index.rst

@@ -15,7 +15,6 @@ diagnostic visualizations.
     how_to_sdec_plot
     how_to_liv_plot
     tutorial_convergence_plot
-    tutorial_montecarlo_packet_visualization
 
 
 TARDIS Widgets (Graphical User Interfaces)

docs/analyzing_tardis/visualization/using_widgets.rst

@@ -179,7 +179,7 @@ you remember to click back on the **Box Select** option for making selections on
 spectrum.
 
 Energy Level Diagram
-################
+####################
 
 This widget lets you visualize the last line interactions
 
@@ -202,7 +202,7 @@ with thicker lines representing more packets than the thin lines.
 The wavelength of the transition is given by the color.
 
 Setting Other Options
------------------
+---------------------
 You can select the range on which to filter the wavelength using the slider.
 You can also select the model shell by which to filter the last line interactions
 and the level populations. If no shell is selected, then all the last line

docs/conf.py

@@ -99,7 +99,7 @@
     "python": ("http://docs.python.org/", None),
     "numpy": ("http://docs.scipy.org/doc/numpy/", None),
     "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
-    "matplotlib": ("http://matplotlib.sourceforge.net/", None),
+    "matplotlib": ("http://matplotlib.org/", None),
     "astropy": ("http://docs.astropy.org/en/stable/", None),
     "h5py": ("http://docs.h5py.org/en/latest/", None),
     "pandas": ("http://pandas.pydata.org/pandas-docs/dev/", None),
@@ -389,7 +389,7 @@ def generate_how_to_guides_page(app):
         if "how_to_" in notebook.name and "checkpoint" not in notebook.name:
             notebooks += f"\n* :doc:`{notebook.parent}/{notebook.stem}`"
 
-    title = "How-To Guides\n*********\n"
+    title = "How-To Guides\n*************\n"
     description = "The following pages contain the TARDIS how-to guides:"
 
     with open("how_to_guides.rst", mode="wt", encoding="utf-8") as f:

docs/contributing/development/code_quality.rst

@@ -30,7 +30,7 @@ To run Ruff, use the following command: ::
 .. note :: We adopt the linting rules utilized by astropy. Permanent rules are defined in the ``pyproject.toml``, non-permanent rules are defined in the ``.ruff.toml`` file. If you want to add a new rule, please add it to the ``.ruff.toml`` file. If you want to add a permanent rule, please open a PR to the ``pyproject.toml``.
 
 Pre-commit (Optional)
-----
+---------------------
 `Pre-commit <https://pre-commit.com/>`_ hooks are tools that help enforce quality standards by running checks on your code before you commit. If you choose to use pre-commit on your local machine, please follow these steps:
 
 Install pre-commit by running: ::

docs/contributing/development/continuous_integration.rst

@@ -136,13 +136,13 @@ and the comparison notebook to Moria. This workflow has a separate job to indica
 bridge has failed.
 
 The Regression Data Comparison Workflow
-======================================
+=======================================
 
 The Regression Data Comparison workflow compares the regression data between the current branch and the base branch on pull requests. It only runs on pull requests and not on the master branch. The workflow generates regression data for the latest commit on the pull request and compares it with the master branch using the comparison notebook. The notebook is then uploaded as an artifact and pushed to reg-data-comp repository for previews in the bot comment.
 
 .. note :: The workflow exports images from the comparison notebook and embeds them in the bot comment. Unless there are any key changes to any of the HDF files in the regression data the bot will only show two images, one containing the spectrum change and another containing relative changes in the keys. If there are any key changes, the bot will show three images, the additional one visualizing the key changes.
 
 The `LFS-cache` workflow
-=======================
+========================
 
 The `LFS-cache` workflow caches the regression data and atomic data and can be triggered either manually or when there is a push to the main branch of the regression data repository. This is mainly responsible for doing LFS pulls when necessary and caching objects while the `setup-lfs` action is used to restore the cached objects. Both fail if the cache is not available.

docs/contributing/development/update_regression_data.rst

@@ -1,8 +1,8 @@
 .. _update regression-data:
 
-*************************
+**************************
 Update the Regression Data
-*************************
+**************************
 
 A special kind of tests are executed only when ``pytest`` is called alongside the ``--tardis-regression-data`` flag. These tests compare the output of the TARDIS code (mostly arrays) against the information stored in the regression data files.
 

docs/installation.rst docs/getting_started/installation.rstdocs/installation.rst renamed to docs/getting_started/installation.rst

@@ -1,5 +1,5 @@
-Code Comparison
-===============
+How to do Code Comparison using TARDIS
+======================================
 
 Several groups have started a comparison of their supernova radiative transfer
 codes to understand systematics uncertainties and different strategies.