Add more complete documentation

.gitignore

@@ -12,3 +12,5 @@ __pycache__
 *,cover
 /.reuse
 __version__.py
+/docs/_build
+/.idea

docs/_ext/custom_autodoc.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2024 Thomas Touhey
+# SPDX-License-Identifier: GPL-3.0-only
+"""Sphinx extension to remove the first line from module docstrings."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def remove_first_line_in_module_docstring(
+    _app: Sphinx,
+    what: str,
+    _name: str,
+    _obj: Any,
+    _options: Any,
+    lines: list[str],
+) -> None:
+    """Remove the first line from the docstring.
+
+    This is because the first line of the docstring is summed up in the
+    document title, before the module autodoc.
+    """
+    if what != "module" or not lines:
+        return
+
+    for i in range(1, len(lines)):
+        if not lines[i]:
+            lines[: i + 1] = []
+            return
+
+    lines[:] = []
+
+
+def setup(app: Sphinx) -> None:
+    """Set up the extension."""
+    app.connect(
+        "autodoc-process-docstring",
+        remove_first_line_in_module_docstring,
+    )

docs/code.rst

@@ -0,0 +1,13 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+Code reference
+==============
+
+If you are looking for information on a specific function, class or method,
+this part of the documentation is for you.
+
+.. toctree::
+    :maxdepth: 1
+
+    code/leapseconddata

docs/code/leapseconddata.rst

@@ -0,0 +1,7 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+``leapseconddata`` -- main namespace for the project
+====================================================
+
+.. automodule:: leapseconddata

docs/conf.py

@@ -17,6 +17,7 @@
 import pathlib
 
 sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+sys.path.append(str(pathlib.Path(__file__).parent / "_ext"))
 
 # Define the canonical URL if you are using a custom domain on Read the Docs
 html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
@@ -29,7 +30,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'leapseconddata'
-copyright = '2021, Jeff Epler'
+copyright = '2021-2024, Jeff Epler'
 author = 'Jeff Epler'
 
 # The full version, including alpha/beta/rc tags
@@ -43,6 +44,9 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'custom_autodoc',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -51,7 +55,10 @@
 # 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', 'Thumbs.db', '.DS_Store', '_env']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_env', '.license']
+
+# Show the contents of todo directives.
+todo_include_todos = True
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -66,8 +73,22 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
 autodoc_typehints = "description"
+autodoc_typehints_format = "short"
 autodoc_class_signature = "separated"
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "inherited-members": False,
+    "special-members": False,
+    "exclude-members": "__init__",
+    "show-inheritance": True,
+}
+autodoc_member_order = "bysource"
 
 # SPDX-FileCopyrightText: 2021 Jeff Epler
 #

docs/developer-guides.rst

@@ -0,0 +1,16 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+Developer guides
+================
+
+This section consists of multiple guides for solving specific problems,
+targeted towards developers using the component.
+
+.. toctree::
+    :maxdepth: 2
+
+    developer-guides/obtaining-leap-seconds
+    developer-guides/converting-tai-to-utc
+    developer-guides/converting-utc-to-tai
+    developer-guides/checking-if-date-is-leap.rst

docs/developer-guides/check-date-leap.py

@@ -0,0 +1,14 @@
+from datetime import date, timedelta
+
+from leapseconddata import LeapSecondData
+
+my_date = date(2015, 12, 31)
+data = LeapSecondData.from_standard_source()
+
+for leap in data.leap_seconds:
+    time = leap.start - timedelta(seconds=1)
+    if my_date.year == time.year and my_date.month == time.month and my_date.day == time.day:
+        print(f"{my_date} has a leap second!")
+        break
+else:
+    print(f"{my_date} does not have a leap second.")

docs/developer-guides/check-date-leap.py.license

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024 Thomas Touhey
+# SPDX-License-Identifier: Unlicense
+# Placed in a separate file so that it does not appear in the produced docs.

docs/developer-guides/checking-if-date-is-leap.rst

@@ -0,0 +1,21 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+Checking if a date has a leap second
+====================================
+
+In order to check if a date has a leap second, you must first
+obtain the leap second data by using one of the methods described
+in :ref:`devguide-obtaining-leaps`. Then, you can iterate over
+the fetched leap seconds to check for the date.
+
+For example, in order to check if December 31st, 2016 has a leap
+second, you can use the following code:
+
+.. literalinclude:: check-date-leap.py
+
+The output of this program is the following:
+
+.. code-block:: text
+
+    2016-12-31 has a leap second!

docs/developer-guides/convert-tai-to-utc.py

@@ -0,0 +1,9 @@
+from datetime import datetime
+
+from leapseconddata import LeapSecondData, tai
+
+my_date = datetime(2024, 7, 18, 22, 0, 37, tzinfo=tai)
+data = LeapSecondData.from_standard_source()
+
+my_tai_date = data.tai_to_utc(my_date)
+print(my_tai_date.isoformat())

docs/developer-guides/convert-tai-to-utc.py.license

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024 Thomas Touhey
+# SPDX-License-Identifier: Unlicense
+# Placed in a separate file so that it does not appear in the produced docs.

docs/developer-guides/convert-utc-to-tai.py

@@ -0,0 +1,9 @@
+from datetime import UTC, datetime
+
+from leapseconddata import LeapSecondData
+
+my_date = datetime(2024, 7, 18, 22, 0, 0, tzinfo=UTC)
+data = LeapSecondData.from_standard_source()
+
+my_tai_date = data.to_tai(my_date)
+print(my_tai_date.isoformat())

docs/developer-guides/convert-utc-to-tai.py.license

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024 Thomas Touhey
+# SPDX-License-Identifier: Unlicense
+# Placed in a separate file so that it does not appear in the produced docs.

docs/developer-guides/converting-tai-to-utc.rst

@@ -0,0 +1,22 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+Converting a TAI date and time to UTC
+=====================================
+
+.. py:currentmodule:: leapseconddata
+
+In order to convert a TAI date and time to UTC, you must first
+obtain the leap second data by using one of the methods described
+in :ref:`devguide-obtaining-leaps`. Then, you can use the
+:py:meth:`LeapSecondData.tai_to_utc` method to convert the date and time.
+
+For example:
+
+.. literalinclude:: convert-tai-to-utc.py
+
+This program will provide you with the following output:
+
+.. code-block:: text
+
+    2024-07-18T22:00:00g+00:00

docs/developer-guides/converting-utc-to-tai.rst

@@ -0,0 +1,22 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+Converting a UTC date and time to TAI
+=====================================
+
+.. py:currentmodule:: leapseconddata
+
+In order to convert a UTC date and time to TAI, you must first
+obtain the leap second data by using one of the methods described
+in :ref:`devguide-obtaining-leaps`. Then, you can use the
+:py:meth:`LeapSecondData.to_tai` method to convert the date and time.
+
+For example:
+
+.. literalinclude:: convert-utc-to-tai.py
+
+This program will provide you with the following output:
+
+.. code-block:: text
+
+    2024-07-18T22:00:37+00:00

docs/developer-guides/obtaining-leap-seconds.rst

@@ -0,0 +1,64 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+.. _devguide-obtaining-leaps:
+
+Obtaining a list of leap seconds
+================================
+
+.. py:currentmodule:: leapseconddata
+
+In order to obtain the current leap second list, you must use one of
+:py:class:`LeapSecondData` ``from_*`` class methods.
+
+Using the first available standard source
+-----------------------------------------
+
+If you do not have any particular restrictions on your Internet access,
+you can try the "magic" method :py:meth:`LeapSecondData.from_standard_source`,
+which will try known local then network sources:
+
+.. code-block:: python
+
+    from leapseconddata import LeapSecondData
+
+    data = LeapSecondData.from_standard_source()
+    ...
+
+Using a custom file source
+--------------------------
+
+If you have a custom path for the ``leap-seconds.list`` the module can use,
+you can use the :py:meth:`LeapSecondData.from_file` method. For example,
+if your file is located at ``/etc/my-program/leap-seconds.list``:
+
+.. code-block:: python
+
+    from leapseconddata import LeapSecondData
+
+    data = LeapSecondData.from_file("/etc/my-program/leap-seconds.list")
+
+Using a custom URL
+------------------
+
+If you have restrictions on your Internet access and can only access the
+file from a specific URL available to your machine, you can use
+:py:meth:`LeapSecondData.from_url`:
+
+.. code-block:: python
+
+    from leapseconddata import LeapSecondData
+
+    data = LeapSecondData.from_url("https://tz.example/leap-seconds.list")
+
+You can also still try local sources before your custom URL, by using
+:py:meth:`LeapSecondData.from_standard_source` with the ``custom_sources``
+keyword parameter set:
+
+.. code-block:: python
+
+    from leapseconddata import LeapSecondData
+
+    data = LeapSecondData.from_standard_source(
+        custom_sources=["https://tz.example/leap-seconds.list"],
+    )

docs/guides.rst

@@ -0,0 +1,12 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+General guides
+==============
+
+This section consists of multiple guides for solving specific problems.
+
+.. toctree::
+    :maxdepth: 2
+
+    guides/install

docs/guides/install.rst

@@ -0,0 +1,17 @@
+.. SPDX-FileCopyrightText: 2024 Thomas Touhey
+.. SPDX-License-Identifier: GPL-3.0-only
+
+.. _guide-install:
+
+Installing leapseconddata
+=========================
+
+In order to install leapseconddata, the instructions may depend on the system
+you want to install it on.
+
+pip (generic)
+-------------
+
+leapseconddata can be installed via ``pip``::
+
+    pip install leapseconddata