Merge pull request #6 from kesslerlib/docs

docs

Author: Sceki

.github/workflows/build.yml

@@ -35,7 +35,7 @@ jobs:
         pip install sphinx-book-theme
         pip install myst-nb
         cd docs
-        make html linkcheck    
+        make html linkcheck 
     - name: Test
       run: |
         coverage run -m pytest

docs/api.rst

@@ -1,19 +1,21 @@
 .. _api:
 
 API
-#########
+#######
 
 Kessler API
 
-.. toctree::
-   :maxdepth: 2
-   :caption: API Documentation
+.. currentmodule:: kessler
 
-   _autosummary/kessler.cdm
-   _autosummary/kessler.data
-   _autosummary/kessler.event
-   _autosummary/kessler.model
-   _autosummary/kessler.nn
-   _autosummary/kessler.observation_model
-   _autosummary/kessler.plot
-   _autosummary/kessler.util
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   cdm
+   data
+   event
+   model
+   nn
+   observation_model
+   plot
+   util

docs/conf.py

@@ -10,16 +10,13 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-project = 'Kessler'
-copyright = "2020, 2021, 2022, 2023, 2024, 2025, Kessler contributors"
+project = 'kessler'
+copyright = "2020-2025, Kessler contributors"
 author = 'Giacomo Acciarini, Atılım Güneş Baydin, Francesco Pinto'
 
 
 # The full version, including alpha/beta/rc tags
 import kessler
-import sys
-import os
-sys.path.insert(0, os.path.abspath('../'))  # Add the root directory of your repo
 
 release = kessler.__version__
 
@@ -30,24 +27,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_nb", "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.autosummary","sphinx.ext.napoleon"]
-
-
-# build the templated autosummary files
-autosummary_generate = True
-autosummary_imported_members = False
-napoleon_google_docstring = True
-numpydoc_show_class_members = False
-panels_add_bootstrap_css = False
-
-autosectionlabel_prefix_document = True
-
-# katex options
-#
-#
-katex_prerender = True
-
-napoleon_use_ivar = True
+extensions = ["myst_nb",
+              "sphinx.ext.intersphinx",
+              "sphinx.ext.autodoc",
+              "sphinx.ext.autosummary",
+              "sphinx.ext.doctest",
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -64,7 +49,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", ".DS_Store",'jupyter_execute/**/*.ipynb','jupyter_execute/*.ipynb']
+exclude_patterns = ["_build", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -97,7 +82,12 @@
 nb_execution_mode = "force"
 
 nb_execution_excludepatterns = ['basics.ipynb','cdms_analysis_and_plotting.ipynb','LSTM_training.ipynb']
-#autosummary_ignore_module = ['']
+
+# Force printing traceback to stderr on execution error.
+nb_execution_show_tb = True
+
+# Set a longer timeout for notebook execution.
+nb_execution_timeout = 120
 
 latex_engine = "xelatex"
 

docs/index.md

@@ -11,27 +11,23 @@ For more details on the model and results, check out our publications listed in
 
 The authors are [Giacomo Acciarini](https://www.esa.int/gsp/ACT/team/giacomo_acciarini/), [Atılım Güneş Baydin](https://gbaydin.github.io/), [Dario Izzo](https://www.esa.int/gsp/ACT/team/dario_izzo/). The main developer is Giacomo Acciarini (giacomo.acciarini@gmail.com).
 
-   :maxdepth: 1
-   :caption: Getting started
 
-   install.rst
-   capabilities
-   credits
+```{toctree}
+:maxdepth: 1
+:caption: Getting Started
 
+install
+capabilities
+credits
+```
 
-   :maxdepth: 1
-   :caption: Tutorials
+```{toctree}
+:maxdepth: 1
+:caption: Contents
 
-   notebooks/basics
-   notebooks/cdms_analysis_and_plotting
-   notebooks/LSTM_training
-   notebooks/probabilistic_programming_module
-
-
-   :maxdepth: 1
-   :caption: API documentation
-
-   api
+tutorials
+api
+```
 
 Indices and tables
 ==================

docs/tutorials.rst

@@ -0,0 +1,27 @@
+.. _tutorials:
+
+Tutorials
+===============
+
+Basics
+^^^^^^^^^^^
+These tutorials include some basic examples on how to use kessler
+
+.. toctree::
+  :maxdepth: 1
+  
+  notebooks/basics.ipynb
+  notebooks/cdms_analysis_and_plotting.ipynb
+
+Advanced
+^^^^^^^^^^^
+These tutorials are more advanced examples on how to leverage kessler framework 
+for more complex tasks. In particular, we will cover both the deep learning module (where
+kessler is used to predict CDMs) and the probabilistic programming one (where kessler is used
+as a probabilistic generative model for CDMs)
+
+.. toctree::
+  :maxdepth: 1
+
+  notebooks/LSTM_training.ipynb
+  notebooks/probabilistic_programming_module.ipynb

kessler/util.py

@@ -441,30 +441,37 @@ def progress_bar_end(message=None):
         print(message)
 
 def get_ccsds_time_format(time_string):
-    '''
-    Adapted by Andrew Ng, 18/3/2022.
-    Original MATLAB source code found at: https://github.com/nasa/CARA_Analysis_Tools/blob/master/two-dimension_Pc/Main/TransformationCode/TimeTransformations/getCcsdsTimeFormat.m
-    get_ccsds_time_format  -  process and outputs the format of the time string extracted from the CDM. 
-    The CCSDS time format is required to be of the general form
-    yyyy-[mm-dd|ddd]THH:MM:SS[.F*][Z]
-    (1) The date and time fields are separated by a "T".
-    (2) The date field has a four digit year followed by either a two digit 
-        month and two digit day, or a three digit day-of-year.  
-    (3) The year, month, day, and day-of-year fields are separated by a dash.
-    (4) The hours, minutes and seconds fields are each two digits separated 
-        by colons.
-    (5) The fraction of seconds is optional and can have any number of
-        digits.
-    (6) If a fraction of seconds is provided, it is separated from the two
-        digit seconds by a period.
-    (7) The time string can end with an optional "Z" time zone indicator
+    """
+    Adapted by Andrew Ng, 18/3/2022.  
+    Original MATLAB source code:  
+    `NASA CARA Analysis Tools <https://github.com/nasa/CARA_Analysis_Tools>`_  
+
+    Processes and outputs the format of the time string extracted from the CDM.  
+    The CCSDS time format is required to be of the general form:  
+
+    .. code-block:: none
+
+        yyyy-[mm-dd|ddd]THH:MM:SS[.F*][Z]
+
+    Format Rules:
+        1. The date and time fields are separated by a **"T"**.
+        2. The date field consists of a **four-digit year**, followed by either:
+            - A two-digit month and a two-digit day, or  
+            - A three-digit day-of-year.
+        3. The year, month, day, and day-of-year fields are separated by a **dash ("-")**.
+        4. The hours, minutes, and seconds fields are **two-digit values** separated by **colons (":")**.
+        5. The fraction of seconds is optional and can have **any number of digits**.
+        6. If a fraction of seconds is provided, it is separated from the two-digit seconds by a **period (".")**.
+        7. The time string can end with an optional **"Z"** time zone indicator.
 
     Args:
-        - time_string(``str``): Original time string stored in CDM.
-    Returns: 
-        - time_format(``str``): Outputs the format of the time string. It must be of the form yyyy-[mm-dd|ddd]THH:MM:SS[.F*][Z], otherwise it is invalid and a RuntimeError is raised.
+        time_string (str): Original time string stored in CDM.
+
+    Returns:
+        str: Outputs the format of the time string.  
+        Must be of the form **yyyy-[mm-dd|ddd]THH:MM:SS[.F*][Z]**, otherwise a `RuntimeError` is raised.
+    """
 
-    '''
     time_format = []
     numT = time_string.count('T')
     if numT == -1:
@@ -508,7 +515,7 @@ def get_ccsds_time_format(time_string):
 def doy_2_date(value, doy, year, idx):
     '''
     Written by Andrew Ng, 18/03/2022, 
-    Based on source code @ https://github.com/nasa/CARA_Analysis_Tools/blob/master/two-dimension_Pc/Main/TransformationCode/TimeTransformations/DOY2Date.m
+    Based on source code @ https://github.com/nasa/CARA_Analysis_Tools
     Use the datetime python package. 
     doy_2_date  - Converts Day of Year (DOY) date format to date format.