Merge pull request #19 from python/readme_docs

Flesh out readme / documentation

Author: pganssle

.github/workflows/tests.yml

@@ -31,7 +31,7 @@ jobs:
     runs-on: "ubuntu-latest"
     strategy:
       matrix:
-        toxenv: ["build", "pytype"]
+        toxenv: ["build", "pytype", "docs"]
     env:
       TOXENV: ${{ matrix.toxenv }}
 
@@ -47,4 +47,8 @@ jobs:
           python -m pip install --upgrade tox
       - name: Run action
         run: |
-          tox
+          if [[ $TOXENV == "docs" ]]; then
+            tox -- -j auto -bhtml -W -n -a --keep-going
+          else
+            tox
+          fi

.gitignore

@@ -10,6 +10,7 @@ dist/
 
 # Sphinx documentation
 docs/_build/
+docs/_output/
 
 # Testing
 .cache

.readthedocs.yml

@@ -0,0 +1,7 @@
+version: 2 # Required in order to install with pip
+
+python:
+  version: 3.7
+  install:
+    - path: .
+    - requirements: docs/requirements.txt

README.md

@@ -0,0 +1,12 @@
+tzdata: Python package providing IANA time zone data
+====================================================
+
+This is a Python package containing ``zic``-compiled binaries for the IANA time
+zone database. It is intended to be a fallback for systems that do not have
+system time zone data installed (or don't have it installed in a standard
+location), as a part of `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_
+
+This repository generates a ``pip``-installable package, published on PyPI as
+`tzdata <https://pypi.org/project/tzdata>`_.
+
+For more information, see `the documentation <https://tzdata.readthedocs.io>`_.

README.rst

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import sphinx_bootstrap_theme
+import tzdata
+
+# -- Project information -----------------------------------------------------
+
+project = "tzdata"
+copyright = "2020, Python Software Foundation"
+author = "Python Software Foundation"
+version = tzdata.__version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.intersphinx"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "bootstrap"
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+html_theme_options = {
+    "bootswatch_theme": "cosmo",
+}
+
+# For cross-links to other documentation
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "dateutil": ("https://dateutil.readthedocs.io/en/stable/", None),
+}

docs/conf.py

@@ -0,0 +1,130 @@
+tzdata: Python package providing IANA time zone data
+====================================================
+
+This is a Python package containing ``zic``-compiled binaries for the IANA time
+zone database. It is intended to be a fallback for systems that do not have
+system time zone data installed (or don't have it installed in a standard
+location), as a part of `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_
+
+This repository generates a ``pip``-installable package, published on PyPI as
+`tzdata <https://pypi.org/project/tzdata>`_.
+
+Overview
+--------
+
+``tzdata`` is a *data-only* package, organized in such a way that its resources
+are accessible via :mod:`importlib.resources` (or, in older versions of Python,
+its backport `importlib_resources`_). Although ``importlib.resources`` or
+equivalent is recommended, it is also possible to access the data via
+:func:`pkgutil.get_data` as well.
+
+.. TODO: Change ``zoneinfo`` to :mod:`zoneinfo` when 3.9 is released
+
+It is primarily intended to be used by standard library's ``zoneinfo``
+module (new in Python 3.9), but it is also available as a source for time zone
+data for other time zone libraries. It is generally recommended that any time
+zone libraries should attempt to use the system data before using the
+``tzdata`` package, but some systems (notably Windows) do not deploy zoneinfo
+binaries of this type, and so ``tzdata`` is necessary.
+
+Contents
+--------
+
+The ``tzdata`` package provides the output of ``zic`` compilation (the
+equivalent of something like ``/usr/share/zoneinfo``) under the
+``tzdata.zoneinfo`` package unaltered. This includes the ``tzdata.zi`` file,
+which is a compact text representation of the un-compiled time zone database.
+
+The package organization looks something like this::
+
+    src/tzdata
+    ├── __init__.py
+    ├── zoneinfo
+    │   ├── __init__.py
+    │   ├── Africa
+    │   │   ├── __init__.py
+    │   │   ├── Abidjan
+    │   │   ├── Accra
+    │   │   ├── …
+    │   │   └── Windhoek
+    │   ├── America
+    │   │   ├── __init__.py
+    │   │   ├── Adak
+    │   │   ├── Anchorage
+    │   │   ├── …
+    │   │   └── Yellowknife
+    │   ├── …
+    │   ├── tzdata.zi
+    │   ├── …
+    │   ├── zone.tab
+    │   └── Zulu
+    └── zones
+
+    21 directories, 623 files
+
+In addition to the zoneinfo files, it also provides a small amount of extra
+metadata about the time zones. The ``tzdata.zones`` file is a newline-delimited
+file listing all the IANA keys for time zone files present in the
+``tzdata.zoneinfo`` package. The version of the IANA data is provided as a
+Python variable as ``tzdata.IANA_VERSION``.
+
+Examples
+--------
+
+End users should generally **not** need to use this package directly and should
+use a Python library  like :mod:`dateutil.tz` or `zoneinfo`_, like so:
+
+.. code-block:: python
+
+    # Python 3.9+
+    from datetime import datetime
+    from zoneinfo import ZoneInfo
+
+    dt = datetime.now(ZoneInfo("America/New_York"))
+
+For those writing time zone libraries, the recommended mechanism for access is
+to open the relevant zoneinfo binaries with
+:func:`importlib.resources.open_binary`, like so:
+
+.. code-block:: python
+
+    from importlib import resources
+
+    # America/New_York
+    with resources.open_binary("tzdata.zoneinfo.America", "New_York") as f:
+        assert f.read(4) == b"TZif"
+
+Note that the way this is organized, each folder in ``tzdata.zoneinfo`` is a
+package with resources below it. An example function for converting IANA keys
+to package names:
+
+.. code-block:: python
+
+    def iana_key_to_resource(key):
+        package_loc, resource = key.rsplit("/", 1)
+        package = "tzdata.zoneinfo." + package_loc.replace("/", ".")
+
+        return package, resource
+
+    assert iana_key_to_resource("America/New_York") == \
+           ("tzdata.zoneinfo.America", "New_York")
+    assert iana_key_to_resource("America/Indiana/Indianapolis") == \
+           ("tzdata.zoneinfo.America.Indiana", "Indianapolis")
+
+.. Links
+
+.. _importlib_resources: https://importlib-resources.readthedocs.io/en/latest/
+.. _zoneinfo: https://docs.python.org/3/library/zoneinfo.html
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/index.rst

@@ -0,0 +1,2 @@
+sphinx>=3.0.0
+sphinx_bootstrap_theme

docs/requirements.txt

@@ -2,8 +2,8 @@
 name = tzdata
 version = attr:tzdata.__version__
 description = Provider of IANA time zone data
-long_description = file: README.md
-long_description_content_type = text/markdown
+long_description = file: README.rst
+long_description_content_type = text/x-rst
 url = https://github.com/python/tzdata
 author = Python Software Foundation
 author_email = [email protected]
@@ -21,6 +21,7 @@ classifiers =
 project_urls =
     Bug Reports = https://github.com/python/tzdata/issues
     Source = https://github.com/python/tzdata
+    Documentation = https://tzdata.readthedocs.io
 
 [options]
 packages = tzdata

setup.cfg

@@ -41,6 +41,14 @@ commands =
     isort update.py
     isort --atomic -rc tests
 
+[testenv:docs]
+description = Build the documentation
+deps =
+    -rdocs/requirements.txt
+commands =
+    sphinx-build -d "{toxworkdir}/docs_doctree" "{toxinidir}/docs" \
+                    "{toxinidir}/docs/_output" {posargs: -j auto --color -bhtml}
+
 [testenv:build]
 description = Build a wheel and source distribution
 skip_install = True