docs: move API references to new page

doc/source/api_reference/API-Reference.rst

@@ -0,0 +1,10 @@
+=============
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    ./eop.rst
+    ./time.rst
+    ./utilities.rst

doc/source/api_reference/eop.rst

@@ -1,6 +1,6 @@
-===
-eop
-===
+=======
+``eop``
+=======
 
 Utilities for maintaining Earth Orientation Parameter (EOP) files
 

doc/source/api_reference/time.rst

@@ -1,6 +1,8 @@
-====
-time
-====
+.. _api-time:
+
+========
+``time``
+========
 
 Utilities for calculating time operations
 

doc/source/api_reference/utilities.rst

@@ -1,6 +1,6 @@
-=========
-utilities
-=========
+=============
+``utilities``
+=============
 
 Download and management utilities for syncing time and auxiliary files
 

doc/source/conf.py

@@ -46,6 +46,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "matplotlib.sphinxext.plot_directive",
+    "myst_nb",
     "numpydoc",
     "sphinxcontrib.bibtex",
     "sphinx.ext.autodoc",
@@ -55,6 +57,27 @@
     "sphinxarg.ext",
 ]
 
+# use myst for notebooks
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+}
+# execute notebooks on build
+if on_rtd:
+    nb_execution_mode = "auto"
+    nb_execution_excludepatterns = [
+        "notebooks/*.ipynb",
+    ]
+    nb_output_stderr = "remove-warn"
+elif on_github:
+    nb_execution_mode = "off"
+else:
+    nb_execution_mode = "auto"
+    nb_execution_excludepatterns = [
+        "notebooks/*.ipynb",
+    ]
+    nb_output_stderr = "remove-warn"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -73,6 +96,11 @@
 pygments_style = "native"
 bibtex_bibfiles = ["_assets/timescale-refs.bib"]
 bibtex_default_style = "plain"
+plot_formats = ["png"]
+plot_html_show_formats = False
+plot_html_show_source_link = False
+numfig = True
+numfig_secnum_depth = 1
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -82,6 +110,12 @@
 html_show_sphinx = True
 html_show_copyright = True
 
+numfig_format = {
+    "code-block": None,
+    "figure": "Figure %s:",
+    "table": "Table %s:",
+}
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #

doc/source/getting_started/Getting-Started.ipynb

@@ -0,0 +1,136 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "2e01086c",
+   "metadata": {},
+   "source": [
+    "# Getting Started\n",
+    "\n",
+    "\n",
+    "This documentation is intended to explain how to compute time conversions and offsets using `timescale`.\n",
+    "\n",
+    "## Time\n",
+    "\n",
+    "The {py:mod}`time <timescale.time>` module can convert different time formats to the necessary time format of a given program.\n",
+    "It can also parse date strings describing the units and epoch of relative times, or the calendar date of measurement for geotiff formats.\n",
+    "`timescale` keeps updated tables of leap seconds for converting from GPS, LORAN and TAI times.\n",
+    "\n",
+    "### Standards\n",
+    "\n",
+    "- **TAI time**: International Atomic Time which is computed as the weighted average of several hundred atomic clocks.\n",
+    "- **UTC time**: Coordinated Universal Time which is [periodically adjusted](https://www.nist.gov/pml/time-and-frequency-division/leap-seconds-faqs) to account for the difference between the definition of the second and the rotation of Earth.\n",
+    "- **GPS time**: Atomic timing system for the Global Positioning System constellation of satellites monitored by the United States Naval Observatory (USNO). GPS time and UTC time were equal on January 6, 1980. TAI time is ahead of GPS time by 19 seconds.\n",
+    "- **LORAN time**: Atomic timing system for the Loran-C chain transmitter sites used in terrestrial radionavigation. LORAN time and UTC time were equal on January 1, 1958. TAI time is ahead of LORAN time by 10 seconds.\n",
+    "\n",
+    "### Dynamic Time\n",
+    "\n",
+    "`timescale` also keeps updated tables of delta times for converting between dynamic (TT) and universal (UT1) times.\n",
+    "Delta times (TT - UT1) are the differences between Dynamic Time (TT) and Universal Time (UT1) {cite:p}`Meeus:1991vh`.\n",
+    "Universal Time (UT1) is based on the rotation of the Earth, which varies irregularly, and so UT1 is adjusted periodically.\n",
+    "Dynamic Time (TT) is a uniform, monotonically increasing time standard based on atomic clocks that is used for the accurate calculation of celestial mechanics, orbits and ephemerides.\n",
+    "Delta times can be added to Universal Time (UT1) values to convert to Dynamic Time (TT) values.\n",
+    "\n",
+    "```{tip}    \n",
+    "See the [project background on time](https://pytmd.readthedocs.io/en/latest/background/Time.html) for more information on time standards and scales\n",
+    "```\n",
+    "\n",
+    "## Functionality\n",
+    "\n",
+    "{py:class}`Timescale <timescale.time.Timescale>` objects can be used to convert between date and time formats.\n",
+    "There are a few different ways to create a {py:class}`Timescale <timescale.time.Timescale>` object:\n",
+    "\n",
+    "1. Range of dates  \n",
+    "2. Delta times  \n",
+    "3. `datetime` objects  \n",
+    "4. Calendar dates  \n",
+    "5. Julian dates  "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "67db92dc",
+   "metadata": {
+    "tags": [
+     "remove-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import datetime\n",
+    "import numpy as np\n",
+    "import timescale.time"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "64b5ab35",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# range of dates\n",
+    "ts = timescale.from_range(\"2018-01-01\", \"2018-12-31\", 1)\n",
+    "\n",
+    "# delta times\n",
+    "delta_time = np.arange(365) * timescale.time._to_sec[\"day\"]\n",
+    "ts = timescale.from_deltatime(delta_time, epoch=(2018, 1, 1, 0, 0, 0))\n",
+    "\n",
+    "# datetime objects\n",
+    "date = datetime.datetime(2018, 1, 1, 0, 0, 0)\n",
+    "ts = timescale.from_datetime(date)\n",
+    "\n",
+    "# calendar dates\n",
+    "year = 2018\n",
+    "month = 1\n",
+    "day = 1 + np.arange(31)\n",
+    "ts = timescale.from_calendar(year, month, day)\n",
+    "\n",
+    "# Julian dates\n",
+    "JD = np.arange(2458119.5, 2458150.5, 1)\n",
+    "ts = timescale.from_julian(JD)\n",
+    "\n",
+    "# inspect timescale\n",
+    "ts"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6ed27a46",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "{py:class}`Timescale <timescale.time.Timescale>` objects can be used to convert epochs, convert to different time standards, convert to `datetime` arrays, and other time conversions.\n",
+    "\n",
+    "```{tip}    \n",
+    "See the {ref}`API Reference <api-time>` for more details on the capabilities\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "py13",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}