Revamp docs and add page on IDL-fiasco comparisons (#259)

* use conda to get graphviz

* switch to pydata theme

* move api docs and bibliography into the same section

* remove unused changelog page

* reorganize docs into quick start, topic guides, and how-to guides

* reorganize landing page

* include secondary sidebar

* fix link

* separate gallery into subsections, with one for IDL comparisons

* fix missing link

* fix package name

* add ioneq comparison

* add gallery example comparing ioneq

* make path to dbase a kwarg

* fix link to reference page

* fix example to include corrected computed rates

* update continuum test data

* add continuum comparison example

* add contribution function comparison

* move test file list to single external file

* always make paths in config a pathlib

* skip the doctests in quickstart for now

* docs build needs asdf-astropy

* add a function in the tools dir to update the test file list

* add rate files to test file list

* reorganize api docs a bit

Author: wtbarnes

.gitignore

@@ -1,3 +1,5 @@
+docs/sg_execution_times.rst
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.readthedocs.yml

@@ -9,12 +9,16 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "mambaforge-4.10"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
+# Using conda to get a working version of graphviz
+conda:
+  environment: .rtd-environment.yml
+
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []
 

.rtd-environment.yml

@@ -0,0 +1,7 @@
+name: rtd_fiasco
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11
+  - pip
+  - graphviz!=2.42.*,!=2.43.*

docs/chianti.rst

@@ -41,6 +41,7 @@
     'sphinx_automodapi.automodapi',
     'sphinx_automodapi.smart_resolver',
     'sphinxcontrib.bibtex',
+    'sphinx_design',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -91,13 +92,38 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = 'sphinx_book_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # -- Sphinx Book Theme Options -----------------------------------------------------
 html_theme_options = {
-    "repository_url": 'https://github.com/wtbarnes/fiasco',
-    "use_repository_button": True,
-    "use_issues_button": True,
+    "use_edit_page_button": True,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/wtbarnes/fiasco",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/fiasco/",
+            "icon": "fa-brands fa-python",
+        },
+        {
+            "name": "CHIANTI",
+            "url": "http://chiantidatabase.org/",
+            "icon": "fa-solid fa-wine-glass",
+        }
+    ],
+    #"secondary_sidebar_items": {
+    #    "index": []  # Remove secondary sidebar on landing page
+    #},
+    "announcement": "fiasco currently only supports version 8 of the CHIANTI database.",
+}
+html_context = {
+    "github_user": "wtbarnes",
+    "github_repo": "fiasco",
+    "github_version": "main",
+    "doc_path": "docs",
 }
 html_logo = '_static/fiasco-logo.png'
 
@@ -127,7 +153,7 @@
 
 # On Read the Docs and CI, download the database and build a minimal HDF5 version
 if ON_RTD or ON_GHA:
-    from fiasco.util import build_hdf5_dbase, download_dbase
+    from fiasco.util import build_hdf5_dbase, download_dbase, get_test_file_list
     from fiasco.util.setup_db import CHIANTI_URL, LATEST_VERSION
     FIASCO_HOME = pathlib.Path.home() / '.fiasco'
     FIASCO_HOME.mkdir(exist_ok=True, parents=True)
@@ -137,43 +163,7 @@
     build_hdf5_dbase(
         ascii_dbase_root,
         hdf5_dbase_root,
-        files=[
-            'chianti.ip',
-            'chianti.ioneq',
-            'sun_coronal_1992_feldman_ext.abund',
-            'sun_coronal_1992_feldman.abund',
-            'c_1.diparams',
-            'c_2.diparams',
-            'c_2.drparams',
-            'c_2.rrparams',
-            'c_3.diparams',
-            'c_3.drparams',
-            'c_3.easplups',
-            'c_3.rrparams',
-            'c_4.diparams',
-            'c_4.drparams',
-            'c_4.easplups',
-            'c_4.rrparams',
-            'c_5.diparams',
-            'c_5.drparams',
-            'c_5.rrparams',
-            'c_6.diparams',
-            'c_6.drparams',
-            'c_6.rrparams',
-            'c_7.rrparams',
-            'fe_5.elvlc',
-            'fe_15.elvlc',
-            'fe_16.diparams',
-            'fe_16.drparams',
-            'fe_16.easplups',
-            'fe_16.rrparams',
-            'fe_18.elvlc',
-            'fe_18.wgfa',
-            'fe_18.scups',
-            'o_6.scups',
-            'o_6.elvlc',
-            'o_6.wgfa',
-        ]
+        files=get_test_file_list(),
     )
     with (FIASCO_HOME / 'fiascorc').open('w') as f:
         c = configparser.ConfigParser()
@@ -183,10 +173,17 @@
         c.write(f)
 
 # -- Sphinx gallery -----------------------------------------------------------
+from sphinx_gallery.sorting import ExampleTitleSortKey, ExplicitOrder  # NOQA: E402
+
 extensions += ['sphinx_gallery.gen_gallery']
 sphinx_gallery_conf = {
-     'examples_dirs': '../examples',   # path to your example scripts
-     'gallery_dirs': 'generated/gallery',  # path to where to save gallery generated output
-     'filename_pattern': '^((?!skip_).)*$',
-     'default_thumb_file': '_static/fiasco-logo.png'
+    'subsection_order': ExplicitOrder([
+        '../examples/user_guide/',
+        '../examples/idl_comparisons/',
+    ]),
+    'within_subsection_order': ExampleTitleSortKey,
+    'examples_dirs': '../examples',   # path to your example scripts
+    'gallery_dirs': 'generated/gallery',  # path to where to save gallery generated output
+    'filename_pattern': '^((?!skip_).)*$',
+    'default_thumb_file': '_static/fiasco-logo.png'
 }