docs/new-theme-cfg (#104)

* add index pages to each module, fix toc tree and link structure * add custom domain base url * update changelog * include TypeError raised from astropy for nan GS radec test
spacetelescope · Nov 25, 2024 · 401f2c0 · 401f2c0
1 parent 1ab2cc2
commit 401f2c0
Show file tree

Hide file tree

Showing 48 changed files with 499 additions and 350 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,10 @@
 1.1.2 (unreleased)
 ==================
 
+docs
+----
+- Use furo as sphinx theme, improve page hierarchy and add custom domain [#104]
+
 preprocessor
 ------------
 - explicitly pass `encoding=bytes` in transform.hypersonic_pliers for numpy 2 compatibility where this will no longer be the default for np.loadtxt [#92]

diff --git a/docs/Makefile b/docs/Makefile
@@ -100,4 +100,7 @@ linkcheck:
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,19 +1,19 @@
 setuptools==70.2.0
-Sphinx==8.0.2
-sphinx-automodapi==0.17.0
-sphinx_rtd_theme==2.0.0
+Sphinx==8.1.3
+sphinx-automodapi==0.18.0
+furo==2024.8.6
 matplotlib==3.8.4
 tensorflow==2.17.0
 numpy==2.1.1
 numpydoc==1.7.0
-astropy==6.1.1
-pydot==2.0.0
+astropy==6.1.4
+pydot==3.0.2
 graphviz==0.20.3
 astroquery==0.4.7
-boto3==1.28.7
-plotly==5.20.0
+boto3==1.35.54
+plotly==5.24.1
 progressbar==2.5
 scikit-learn==1.5.2
-scikeras==0.11.0
-tables==3.9.2
-tqdm==4.66.5
+scikeras==0.13.0
+tables==3.10.1
+tqdm==4.66.6
diff --git a/docs/source/analyzer/compute.rst b/docs/source/analyzer/compute.rst
@@ -3,7 +3,7 @@
 *************************
 spacekit.analyzer.compute
 *************************
- 
+
 .. currentmodule:: spacekit.analyzer.compute
 
 .. inheritance-diagram:: spacekit.analyzer.compute

diff --git a/docs/source/analyzer/index.rst b/docs/source/analyzer/index.rst
@@ -0,0 +1,15 @@
+.. _analyzer:
+
+*****************
+spacekit.analyzer
+*****************
+
+.. currentmodule:: spacekit.analyzer
+
+.. toctree::
+   :maxdepth: 1
+
+   compute <compute.rst>
+   explore <explore.rst>
+   scan <scan.rst>
+   track <track.rst>
diff --git a/docs/source/analyzer/track.rst b/docs/source/analyzer/track.rst
@@ -4,9 +4,12 @@
 spacekit.analyzer.track
 ***********************
 
+.. currentmodule:: spacekit.analyzer.track
+
+
 This module tracks the start, end clocktime intervals for a running process and record the total duration. Optionally the timestamps and durations for multiple processes can be logged in a single text file on disk (or separate files if desired).
 
-.. currentmodule:: spacekit.analyzer.track
+
 
 .. autofunction:: proc_time
 

diff --git a/docs/source/builder/architect.rst b/docs/source/builder/architect.rst
@@ -4,6 +4,7 @@
 spacekit.builder.architect
 **************************
 
+
 .. currentmodule:: spacekit.builder.architect
 
 .. inheritance-diagram:: spacekit.builder.architect

diff --git a/docs/source/builder/blueprints.rst b/docs/source/builder/blueprints.rst
@@ -1,11 +1,12 @@
-.. _blueprint:
+.. _blueprints:
 
 ***************************
 spacekit.builder.blueprints
 ***************************
 
 .. currentmodule:: spacekit.builder.blueprints
 
+
 .. autoclass:: Blueprint
    :members:
    :undoc-members:

diff --git a/docs/source/builder/index.rst b/docs/source/builder/index.rst
@@ -0,0 +1,13 @@
+.. _builder
+
+*****************
+spacekit.builder
+*****************
+
+.. currentmodule:: spacekit.builder
+
+.. toctree::
+   :maxdepth: 1
+
+   architect <architect.rst>
+   blueprints <blueprints.rst>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -16,8 +16,7 @@
 import importlib
 from packaging.version import Version
 from configparser import ConfigParser
-# import sphinx
-# import stsci_rtd_theme
+
 
 
 def setup(app):
@@ -179,7 +178,7 @@ def setup(app):
 # a list of builtin themes.
 # html_theme = 'stsci_rtd_theme'
 # html_theme_path = [stsci_rtd_theme.get_html_theme_path()]
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -208,7 +207,7 @@ def setup(app):
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {"**": ["globaltoc.html", "relations.html", "searchbox.html"]}
+# html_sidebars = {"**": ["globaltoc.html", "relations.html", "searchbox.html"]}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -220,6 +219,8 @@ def setup(app):
 # If false, no index is generated.
 html_use_index = True
 
+html_baseurl = "https://docs.spacekit.org"
+
 # If true, the index is split into individual pages for each letter.
 # html_split_index = False
 

diff --git a/docs/source/dashboard/cal.rst b/docs/source/dashboard/cal.rst
@@ -1,3 +1,6 @@
 **********************
 spacekit.dashboard.cal
 **********************
+
+
+.. currentmodule:: spacekit.dashboard.cal
diff --git a/docs/source/dashboard/index.rst b/docs/source/dashboard/index.rst
@@ -0,0 +1,13 @@
+.. _dashboard
+
+*****************
+spacekit.dashboard
+*****************
+
+.. currentmodule:: spacekit.dashboard
+
+.. toctree::
+   :maxdepth: 1
+
+   cal <cal.rst>
+   svm <svm.rst>
diff --git a/docs/source/dashboard/svm.rst b/docs/source/dashboard/svm.rst
@@ -1,3 +1,5 @@
 **********************
 spacekit.dashboard.svm
-**********************
+**********************
+
+.. currentmodule:: spacekit.dashboard.svm
diff --git a/docs/source/datasets/index.rst b/docs/source/datasets/index.rst
@@ -0,0 +1,12 @@
+.. _datasets
+
+*****************
+spacekit.datasets
+*****************
+
+.. currentmodule:: spacekit.datasets
+
+.. toctree::
+   :maxdepth: 1
+
+   beam <beam.rst>
diff --git a/docs/source/extractor/index.rst b/docs/source/extractor/index.rst
@@ -0,0 +1,14 @@
+.. _extractor
+
+******************
+spacekit.extractor
+******************
+
+.. currentmodule:: spacekit.extractor
+
+.. toctree::
+   :maxdepth: 1
+
+   load <load.rst>
+   radio <radio.rst>
+   scrape <scrape.rst>
diff --git a/docs/source/extractor/radio.rst b/docs/source/extractor/radio.rst
@@ -6,6 +6,7 @@ spacekit.extractor.radio
 
 .. currentmodule:: spacekit.extractor.radio
 
+
 Querying and downloading .fits files from a MAST s3 bucket on AWS. Unlike `spacekit.extractor.scrape <spacekit.extractor.scrape>`_, which can access data in private s3 buckets, this module is specifically for collecting data from the publicly available MAST website and/or MAST data hosted on s3. Instead of scraping a closed collection, you're receiving data from an open channel - like a radio.
 
 .. autoclass:: Radio

diff --git a/docs/source/generator/augment.rst b/docs/source/generator/augment.rst
@@ -4,5 +4,7 @@
 spacekit.generator.augment
 **************************
 
+.. currentmodule:: spacekit.generator.augment
+
 .. automodule:: spacekit.generator.augment
    :members:
diff --git a/docs/source/generator/index.rst b/docs/source/generator/index.rst
@@ -0,0 +1,13 @@
+.. _generator
+
+******************
+spacekit.generator
+******************
+
+.. currentmodule:: spacekit.generator
+
+.. toctree::
+   :maxdepth: 1
+
+   augment <augment.rst>
+   draw <draw.rst>
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -5,113 +5,23 @@ spacekit documentation
 This is the documentation for ``spacekit``,
 the Astronomical Data Science and Machine Learning Toolkit 
 
-Reference/API
-=============
-
-
-Analyzer
---------
-
-.. toctree::
-   :maxdepth: 1
-
-   compute <analyzer/compute.rst>
-   explore <analyzer/explore.rst>
-   scan <analyzer/scan.rst>
-   track <analyzer/track.rst>
-
-
-Builder
--------
-
-.. toctree::
-   :maxdepth: 1
-
-   architect <builder/architect.rst>
-   blueprints <builder/blueprints.rst>
-
-
-Dashboard
----------
-
-.. toctree::
-   :maxdepth: 1
-
-   cal <dashboard/cal.rst>
-   svm <dashboard/svm.rst>
-
-
-Datasets
----------
-
-.. toctree::
-   :maxdepth: 1
-
-   beam <datasets/beam.rst>
-
-
-Extractor
----------
-
-.. toctree::
-   :maxdepth: 1
-
-   load <extractor/load.rst>
-   radio <extractor/radio.rst>
-   scrape <extractor/scrape.rst>
-
-
-Generator
----------
-
-.. toctree::
-   :maxdepth: 1
-
-   augment <generator/augment.rst>
-   draw <generator/draw.rst>
-
-
-Logger
-------
-
 .. toctree::
    :maxdepth: 1
 
-   log <logger/log.rst>
-
-
-Preprocessor
-------------
-
-.. toctree::
-   :maxdepth: 1
-
-   encode <preprocessor/encode.rst>
-   ingest <preprocessor/ingest.rst>
-   prep <preprocessor/prep.rst>
-   scrub <preprocessor/scrub.rst>
-   transform <preprocessor/transform.rst>
-
-
-Skøpes: Space Telescope Machine Learning Applications
------------------------------------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   James Webb Space Telescope <skopes/jwst.rst>
-      Calibration Pipeline Resource Prediction Modeling <skopes/jwst/cal.rst>
-
-   Hubble Space Telescope <skopes/hst.rst>
-      Single Visit Mosaic Alignment Modeling <skopes/hst/svm.rst>
-      Calcloud Data Pipeline Modeling <skopes/hst/cal.rst>
+   Analyzer <analyzer/index.rst>
+   Builder <builder/index.rst>
+   Dashboard <dashboard/index.rst>
+   Datasets <datasets/index.rst>
+   Extractor <extractor/index.rst>
+   Generator <generator/index.rst>
+   Logger <logger/index.rst>
+   Preprocessor <preprocessor/index.rst>
+   Skøpes <skopes/index.rst>
 
-   K2/Kepler Exoplanets <skopes/kepler/light-curves.rst>
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
diff --git a/docs/source/logger/index.rst b/docs/source/logger/index.rst
@@ -0,0 +1,12 @@
+.. _logger
+
+***************
+spacekit.logger
+***************
+
+.. currentmodule:: spacekit.logger
+
+.. toctree::
+   :maxdepth: 1
+
+   log <log.rst>
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,6 +6,7 @@ spacekit.extractor.radio

		.. currentmodule:: spacekit.extractor.radio


		Querying and downloading .fits files from a MAST s3 bucket on AWS. Unlike `spacekit.extractor.scrape <spacekit.extractor.scrape>`_, which can access data in private s3 buckets, this module is specifically for collecting data from the publicly available MAST website and/or MAST data hosted on s3. Instead of scraping a closed collection, you're receiving data from an open channel - like a radio.

		.. autoclass:: Radio
Expand Down