Merge pull request #66 from pganssle/documentation

Update documentation to reflect backport status

README.md

@@ -1,15 +1,48 @@
-# `zoneinfo`: IANA Time Zones for the Standard Library
+# `backports.zoneinfo`: Backport of the standard library module `zoneinfo`
 
-This is the reference implementation for [PEP 615](https://www.python.org/dev/peps/pep-0615/), which proposes support for the IANA time zone database in the standard library.
+This package was originally the reference implementation for [PEP 615](https://www.python.org/dev/peps/pep-0615/), which proposes support for the IANA time zone database in the standard library, and now serves as a backport to Python 3.8.
 
-It exposes the `zoneinfo` module, which uses system time zone data if available, and otherwise falls back to using the [`tzdata`](https://github.com/pganssle/tzdata) package if installed.
+This exposes the `backports.zoneinfo` module, which is a backport of the [`zoneinfo`](https://docs.python.org/3.9/library/zoneinfo.html#module-zoneinfo) module. The backport's documentation can be found [on readthedocs](https://zoneinfo.readthedocs.io/en/latest/).
+
+The module uses the system time zone data if available, and falls back to the [`tzdata`](https://tzdata.readthedocs.io/en/latest/) package (available [on PyPI](https://pypi.org/project/tzdata/)) if installed.
+
+## Installation and depending on this library
+
+This module is called [`backports.zoneinfo`](https://pypi.org/project/backports.zoneinfo) on PyPI. To install it in your local environment, use:
+
+```
+pip install backports.zoneinfo
+```
+
+Or (particularly on Windows), you can also use the `tzdata` extra (which basically just declares a dependency on `tzdata`, so this doesn't actually save you any typing 😅):
+
+```
+pip install backports.zoneinfo[tzdata]
+```
+
+If you want to use this in your application, it is best to use [PEP 508 environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers) to declare a dependency *conditional on the Python version*:
+
+```
+backports.zoneinfo;python_version<"3.9"
+```
+
+Support for `backports.zoneinfo` in Python 3.9+ is currently minimal, since it is expected that you would use the standard library `zoneinfo` module instead.
 
 ## Use
 
-To use this, construct a `ZoneInfo` object and attach it to your datetime:
+The `backports.zoneinfo` module should be a drop-in replacement for the Python 3.9 standard library module `zoneinfo`. If you do not support anything earlier than Python 3.9, **you do not need this library**; if you are supporting Python 3.8+, you may want to use this idiom to "fall back" to ``backports.zoneinfo``:
+
+```python
+try:
+    import zoneinfo
+except ImportError:
+    from backports import zoneinfo
+```
+
+To get access to time zones with this module, construct a `ZoneInfo` object and attach it to your datetime:
 
 ```python
->>> from zoneinfo import ZoneInfo
+>>> from backports.zoneinfo import ZoneInfo
 >>> from datetime import datetime, timedelta, timezone
 >>> dt = datetime(1992, 3, 1, tzinfo=ZoneInfo("Europe/Minsk"))
 >>> print(dt)
@@ -50,4 +83,4 @@ Ambiguous and imaginary times are handled using the `fold` attribute added in [P
 
 # Contributing
 
-Currently we are not accepting contributions to this library because we have not put the CLA in place and we would like to avoid complicating the process of adoption into the standard library.
+Currently we are not accepting contributions to this repository because we have not put the CLA in place and we would like to avoid complicating the process of adoption into the standard library. Contributions to [CPython](https://github.com/python/cpython) will eventually be backported to this repository — see [the Python developer's guide](https://devguide.python.org/) for more information on how to contribute to CPython.

docs/conf.py

@@ -10,6 +10,26 @@
 author = "Paul Ganssle"
 copyright = f"2020, {author}"
 
+# Read the version information from the _version.py file
+def get_version():
+    import ast
+
+    version_line = None
+    with open("../src/backports/zoneinfo/_version.py") as f:
+        for line in f:
+            if line.startswith("__version__ ="):
+                version_line = line
+                break
+
+    if version_line is None:
+        raise ValueError("Version not found!")
+
+    version_str = version_line.split("=", 1)[1].strip()
+
+    return ast.literal_eval(version_str)
+
+
+version = get_version()
 
 # -- General configuration ---------------------------------------------------
 
@@ -32,12 +52,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "python_docs_theme"
+html_theme = "nature"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
 
 # For cross-links to other documentation
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {"python": ("https://docs.python.org/3.9", None)}

docs/index.rst

@@ -1,10 +1,15 @@
-``zoneinfo``: IANA Time Zones for the Standard Library
-======================================================
+``backports.zoneinfo``: A backport of the ``zoneinfo`` module
+=============================================================
 
+This was originally the reference implementation for :pep:`615`, which adds
+support for the IANA time zone database to the Python standard library, but now
+serves as a backport of the module to Python 3.8.
 
-This is the reference implementation for :pep:`615`, which adds support for the IANA time zone database to the Python standard library.
+The upstream documentation can be found at :mod:`zoneinfo`. A mirror of the
+documentation pinned to the version supported in the backport can be found at
+:mod:`backports.zoneinfo`.
 
-See :mod:`zoneinfo` for the module's full documentation.
+This is the documentation for version |version|.
 
 Documentation
 =============

docs/requirements.txt

@@ -1,2 +1 @@
 sphinx>=3.0.0
-python-docs-theme

docs/zoneinfo.rst

@@ -1,24 +1,25 @@
-:mod:`zoneinfo` --- IANA time zone support
-==========================================
+:mod:`backports.zoneinfo` --- IANA time zone support
+====================================================
 
-.. module:: zoneinfo
+.. module:: backports.zoneinfo
     :synopsis: IANA time zone support
 
-.. versionadded:: 3.9
-
 .. moduleauthor:: Paul Ganssle <[email protected]>
 .. sectionauthor:: Paul Ganssle <[email protected]>
 
 --------------
 
-The :mod:`zoneinfo` module provides a concrete time zone implementation to
-support the IANA time zone database as originally specified in :pep:`615`. By
-default, :mod:`zoneinfo` uses the system's time zone data if available; if no
-system time zone data is available, the library will fall back to using the
-first-party `tzdata`_ package available on PyPI.
+The :mod:`~backports.zoneinfo` module provides a concrete time zone
+implementation to support the IANA time zone database as originally specified
+in :pep:`615`. By default, :mod:`~backports.zoneinfo` uses the system's time
+zone data if available; if no system time zone data is available, the library
+will fall back to using the first-party `tzdata`_ package available on PyPI.
 
 .. seealso::
 
+    Module: :mod:`zoneinfo`
+        The standard library module ``zoneinfo``, of which this is a backport.
+
     Module: :mod:`datetime`
         Provides the :class:`~datetime.time` and :class:`~datetime.datetime`
         types with which the :class:`ZoneInfo` class is designed to be used.
@@ -36,7 +37,7 @@ abstract base class, and is intended to be attached to ``tzinfo``, either via
 the constructor, the :meth:`datetime.replace <datetime.datetime.replace>`
 method or :meth:`datetime.astimezone <datetime.datetime.astimezone>`::
 
-    >>> from zoneinfo import ZoneInfo
+    >>> from backports.zoneinfo import ZoneInfo
     >>> from datetime import datetime, timedelta
 
     >>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))

tox.ini

@@ -104,6 +104,7 @@ commands =
 
 [testenv:docs]
 description = Build the documentation
+skip_install = True
 deps =
     -rdocs/requirements.txt
 commands =