Merge branch 'release/0.1.4'

.readthedocs.yaml

@@ -0,0 +1,34 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - method: pip
+    path: .
+    extra_requirements:
+      - docs

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.4 - 2024-10-21
+
+* Add `--skip` options to `earthkit-dateseq previous/next`
+
 ## 0.1.3 - 2024-07-19
 
 * Add `Sequence.nearest` and `earthkit-dateseq nearest`

README.md

@@ -1,12 +1,18 @@
 # earthkit.time
 
-:warning: This project is BETA and will be experimental for the foreseeable
-future. Interfaces and functionality are likely to change, and the project
-itself may be scrapped. DO NOT use this software in any project/software that is
-operational.
+:warning: This project is in the **BETA** stage of development. Please be aware
+that interfaces and functionality may change as the project develops. If this
+software is to be used in operational systems you are **strongly advised to use
+a released tag in your system configuration**, and you should be willing to
+accept incoming changes and bug fixes that require adaptations on your part.
+ECMWF **does use** this software in operations and abides by the same caveats.
 
 Date and time manipulation routines for the use of weather data
 
+## Documentation
+
+The documentation can be found at https://earthkit-time.readthedocs.io.
+
 ## Python API
 
 ### When is the next Tuesday?

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/calendar.rst

@@ -0,0 +1,6 @@
+earthkit.time.calendar - Calendar-related utilities
+===================================================
+
+.. automodule:: earthkit.time.calendar
+    :members:
+    :undoc-members:

docs/api/climatology.rst

@@ -0,0 +1,5 @@
+earthkit.time.climatology - Generate dates to compute model climates
+====================================================================
+
+.. automodule:: earthkit.time.climatology
+    :members:

docs/api/index.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   sequence
+   climatology
+   calendar

docs/api/sequence.rst

@@ -0,0 +1,25 @@
+earthkit.time.sequence - Manipulate sequence of dates
+=====================================================
+
+.. module:: earthkit.time.sequence
+
+Sequence API
+------------
+
+Sequences are described by subclasses of :class:`Sequence`.
+
+.. autoclass:: Sequence
+    :members:
+
+
+Built-in Sequences
+------------------
+
+.. autoclass:: DailySequence
+
+.. autoclass:: WeeklySequence
+
+.. autoclass:: MonthlySequence
+
+.. autoclass:: YearlySequence
+

docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

docs/cli/climdates.rst

@@ -0,0 +1,88 @@
+earthkit-climdates - Compute model climate dates
+================================================
+
+.. program:: earthkit-climdates
+
+The :program:`earthkit-climdates` can be invoked with various actions documented
+here, as follows::
+
+   earthkit-climdates <action> [args...]
+
+.. option:: -h, --help
+
+   Print a help message and exit. Can be used as ``earthkit-climdates --help``
+   as well as for actions, e.g. ``earthkit-climdates range --help``.
+
+
+.. _cli_mclim_range:
+
+``range`` - Compute climatological date ranges
+----------------------------------------------
+
+Compute climatological date ranges, one day per year in a given range::
+
+   earthkit-climdates range [--sep <sep>] (--from-date <start> | --from-year <start>) (--to-date <end> | --to-year <end>) <date>
+
+The list is printed using the given separator, as documented in :ref:`cli_sep`.
+
+.. option:: --from-date <start>
+
+   Return dates starting from this one
+
+.. option:: --from-year <start>
+
+   Return dates starting from this year
+
+.. option:: --to-date <end>
+
+   Return dates up to this one
+
+.. option:: --to-year <end>
+
+   Return dates up to this year
+
+.. option:: date
+
+   The date to use as a reference (YYYYMMDD)
+
+
+``mclim`` - Compute sets of dates for model climatologies
+---------------------------------------------------------
+
+This combines a climatological range (see :ref:`cli_mclim_range`) and a
+recurring source (e.g. twice a week).
+
+Usage::
+
+   earthkit-climdates mclim <sequence> [--sep <sep>] (--from-date <start> | --from-year <start>) (--to-date <end> | --to-year <end>) --before <num> --after <num> <date>
+
+The sequence is described as documented in :ref:`cli_seq`. The list is printed
+using the given separator, as documented in :ref:`cli_sep`.
+
+.. option:: --from-date <start>
+
+   Return dates starting from this one
+
+.. option:: --from-year <start>
+
+   Return dates starting from this year
+
+.. option:: --to-date <end>
+
+   Return dates up to this one
+
+.. option:: --to-year <end>
+
+   Return dates up to this year
+
+.. option:: --before <num>
+
+   Pick up all inputs starting from *num* days before the chosen date
+
+.. option:: --after <num>
+
+   Pick up all inputs up to *num* days after the chosen date
+
+.. option:: date
+
+   The date to use as a reference (YYYYMMDD)

docs/cli/date.rst

@@ -0,0 +1,46 @@
+earthkit-date - Manipulate dates
+================================
+
+.. program:: earthkit-date
+
+The :program:`earthkit-date` can be invoked with various actions documented
+here, as follows::
+
+   earthkit-date <action> [args...]
+
+.. option:: -h, --help
+
+   Print a help message and exit. Can be used as ``earthkit-date --help`` as well as
+   for actions, e.g. ``earthkit-date shift --help``.
+
+
+``shift`` - shift a date
+------------------------
+
+Shift a date by the given number of days::
+
+   earthkit-date shift <date> <days>
+
+.. option:: date
+
+   Reference date
+
+.. option:: days
+
+   Number of days (can be negative)
+
+
+``diff`` - subtract two dates
+-----------------------------
+
+Subtract date2 from date1, returning the number of days::
+
+   earthkit-date diff <date1> <date2>
+
+.. option:: date1
+
+   First date (+)
+
+.. option:: date2
+
+   Second date (-)