Documentation overhaul

[taldcroft]

Description

• Use pydata sphinx theme
• Improve overall organization
• Remove or move some outdated content
• Change API docs to use sphinx-autoapi
  • Remove all the curated API doc pages.

See: https://cxc.cfa.harvard.edu/mta/ASPECT/tests/cheta/pr269/html/index.html

Requires

• Add remote access traceback + fix MSID.iplot() + docs update #268
• sphinx-autoapi
• pydata-sphinx-theme
• sphinx-copybutton

Interface impacts

The symbol ENG_ARCHIVE in cheta.fetch is removed to get rid of a sphinx-autoapi warning. I don't understand the warning but I think removing that symbol is benign. I searched the sot org for fetch.ENG_ARCHIVE and got no code results.

Testing

Unit tests

• Mac

(ska3-flight-2025.0rc2) ➜  cheta git:(docs-pydata) git rev-parse --short HEAD
28b475d
(ska3-flight-2025.0rc2) ➜  cheta git:(docs-pydata) pytest
=============================================== test session starts ================================================
platform darwin -- Python 3.12.8, pytest-8.3.4, pluggy-1.5.0
rootdir: /Volumes/git
configfile: pytest.ini
plugins: doctestplus-1.3.0, anyio-4.7.0, timeout-2.3.1
collected 174 items                                                                                                

cheta/tests/test_comps.py ............................................................                       [ 34%]
cheta/tests/test_data_source.py .........                                                                    [ 39%]
cheta/tests/test_fetch.py ................................                                                   [ 58%]
cheta/tests/test_intervals.py .........................                                                      [ 72%]
cheta/tests/test_orbit.py .                                                                                  [ 72%]
cheta/tests/test_remote_access.py ......                                                                     [ 76%]
cheta/tests/test_sync.py ........                                                                            [ 81%]
cheta/tests/test_units.py ...........                                                                        [ 87%]
cheta/tests/test_units_reversed.py ...........                                                               [ 93%]
cheta/tests/test_utils.py ...........                                                                        [100%]

========================================== 174 passed in 78.95s (0:01:18) ==========================================

Independent check of unit tests by Jean

• OSX arm64

(2025.1rc1) flame:cheta jean$ pytest
====================================================== test session starts =======================================================
platform darwin -- Python 3.12.8, pytest-8.3.4, pluggy-1.5.0
rootdir: /Users/jean/git
configfile: pytest.ini
plugins: anyio-4.7.0, timeout-2.3.1
collected 174 items                                                                                                              

cheta/tests/test_comps.py ............................................................                                     [ 34%]
cheta/tests/test_data_source.py .........                                                                                  [ 39%]
cheta/tests/test_fetch.py ................................                                                                 [ 58%]
cheta/tests/test_intervals.py .........................                                                                    [ 72%]
cheta/tests/test_orbit.py .                                                                                                [ 72%]
cheta/tests/test_remote_access.py ......                                                                                   [ 76%]
cheta/tests/test_sync.py ........                                                                                          [ 81%]
cheta/tests/test_units.py ...........                                                                                      [ 87%]
cheta/tests/test_units_reversed.py ...........                                                                             [ 93%]
cheta/tests/test_utils.py ...........                                                                                      [100%]

======================================================== warnings summary ========================================================
cheta/cheta/tests/test_comps.py::test_cmd_states
  /Users/jean/miniforge3/envs/2025.1rc1/lib/python3.12/site-packages/setuptools_scm/git.py:312: UserWarning: git archive did not support describe output
    warnings.warn("git archive did not support describe output")

cheta/cheta/tests/test_intervals.py::test_fetch_MSID_intervals
  /Users/jean/miniforge3/envs/2025.1rc1/lib/python3.12/site-packages/django/utils/encoding.py:266: DeprecationWarning: 'locale.getdefaultlocale' is deprecated and slated for removal in Python 3.15. Use setlocale(), getencoding() and getlocale() instead.
    encoding = locale.getdefaultlocale()[1] or 'ascii'

cheta/cheta/tests/test_intervals.py::test_fetch_MSID_intervals
  /Users/jean/miniforge3/envs/2025.1rc1/lib/python3.12/site-packages/django/http/request.py:1: DeprecationWarning: 'cgi' is deprecated and slated for removal in Python 3.13
    import cgi

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
=========================================== 174 passed, 3 warnings in 86.06s (0:01:26

Functional tests

Building docs generates no visible warnings and no errors.

For some reason it reports 4 warnings at the end, but the build log does not match warn anywhere else.

[jeanconn]

The test output looks good to me. This will require we add sphinx-autoapi to the docs build environment / ska3-core, but from a trial conda install on osx it doesn't look to bring in much else (stdlib-list-0.11.0) and the set of packages looks to be satisfied from 2025.1rc1 .

[jeanconn]

kady is available again, so I installed sphinx-autoapi in the docs / masters build environment.