Set up for publishing on PyPI (#60)

* Move tox config into setup.cfg #58 (#59)

* Move tox config into setup.cfg #58

Adds a comment documenting everywhere to update python versions
when supported versions change

* Use tox interpolation syntax and declare dependencies once

* Add documentation build to check workflow

* Include docs deps in dev deps

* Configure tox and github actions to use the same base python version

* Python 3.10, not 3.1 GitHub Actions 🙄

* Added label field to UndateInterval, added repr methods, and tests. (#52)

* Added label field to UndateInterval, added repr methods, and tests.

* Added variable documentation for labels.

* dynamically import dateformatter subclasses (#50)

* Use pkgutils to dynamically import dateformat formatter subclasses

* Adjust formatter import and test to confirm we only import once

* Add pytest-ordering dependency to tox

* Use python3.8 compatible caching

* Add pytest-ordering to tox coverage deps

* Create python-publish.yml

* Add docs build directory to gitignore

* Prep for initial publication on PyPI

* Update formatting

* Adjust requirement reference syntax

* Revise project metadata and tox install commands

* Update for formatting & display on PyPI

* Add a change log

* Add readthedocs badge and link, add placeholder text in docs intro

---------

Co-authored-by: Julia Damerow <[email protected]>

.github/workflows/check.yml

@@ -1,4 +1,4 @@
-name: style check
+name: style + docs check
 
 on:
   pull_request:
@@ -13,14 +13,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python 3.9
+      - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.10"
           cache: 'pip'
           cache-dependency-path: '**/setup.cfg'
       - name: Install package with dependencies
         run: pip install -e ".[dev]"
         if: steps.python-cache.outputs.cache-hit != 'true'
       - name: Run black
         run: black src --check --diff
+      - name: Check that documentation can be built
+        run: tox -e docs

.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/unit_tests.yml

@@ -10,7 +10,8 @@ on:
   pull_request:
 
 env:
-  COV_PYTHON_VERSION: "3.9"
+  # python version used to calculate and submit code coverage
+  COV_PYTHON_VERSION: "3.10"
 
 jobs:
   python-unit:

.gitignore

@@ -24,6 +24,7 @@ wheels/
 .installed.cfg
 *.egg
 MANIFEST
+docs/_build/
 
 # Environments
 .tox

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Change Log
+
+## 0.1
+
+Pre-alpha version with preliminary `Undate` and `UndateInterval` classes
+with support for ISO8601 date format

README.md

@@ -1,26 +1,43 @@
 # undate-python
 
-`undate` is a python library for working with uncertain or partially known dates.
+**undate** is a python library for working with uncertain or partially known dates.
+
+It was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hackathon in November 2022.
+
+---
+
+⚠️ **WARNING:** this is pre-alpha software and is **NOT** feature complete! Use with caution. ⚠️
+
+---
 
-It was initially created as part of a DH-Tech hackathon in November 2022.
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Documentation Status](https://readthedocs.org/projects/undate-python/badge/?version=latest)](https://undate-python.readthedocs.io/en/latest/?badge=latest)
 [![unit tests](https://github.com/dh-tech/undate-python/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/dh-tech/undate-python/actions/workflows/unit_tests.yml)
 [![codecov](https://codecov.io/gh/dh-tech/undate-python/branch/main/graph/badge.svg?token=GE7HZE8C9D)](https://codecov.io/gh/dh-tech/undate-python)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
+## Documentation
+
+Project documentation is available on ReadTheDocs https://undate-python.readthedocs.io/en/latest/
+
 ## License
 
 This software is licensed under the [Apache 2.0 License](LICENSE.md).
 
 ## Installation
 
+To install the most recent release from PyPI:
+```sh
+pip install undate
+```
+
 To install the latest development version from GitHub:
 ```sh
-pip install git+https://github.com/dh-tech/undate-python.git@main#egg=undate
+pip install git+https://github.com/dh-tech/undate-python.git@develop#egg=undate
 ```
 
 To install a specific release or branch, run the following (replace `[tag-name]` with the tag or branch you want to install):

docs/conf.py

@@ -17,34 +17,30 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Undate'
-copyright = '2022, DHtech'
-author = 'DHtech Community'
+project = "Undate"
+copyright = "2022, DHtech"
+author = "DHtech Community"
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.1.dev'
+release = "0.0.1.dev"
 
-master_doc = 'index'
+master_doc = "index"
 
 
 # -- 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.autodoc',
-    'sphinx.ext.intersphinx',
-    'm2r2'
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "m2r2"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 source_suffix = [".rst", ".md"]
 
@@ -53,11 +49,11 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # 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 = ['_static']
+html_static_path = ["_static"]
 
-html_logo = '_static/logo.png'
+html_logo = "_static/logo.png"

docs/index.rst

@@ -1,7 +1,7 @@
 Undate documentation
 ====================
 
-This project ...
+**undate** is a python library for working with uncertain or partially known dates.
 
 
 .. toctree::

pytest.ini

@@ -1,3 +1,4 @@
 [pytest]
 markers =
-    last: run marked tests after all others
+    last: run marked tests after all others
+    first: run marked tests before all others

setup.cfg

@@ -1,34 +1,46 @@
 [metadata]
 name = undate
 version = attr: undate.__version__
-author = 'DHTech'
-author_email = '[email protected]'
-description = "library for working with uncertain, fuzzy, or "
-    + "partially unknown dates and date intervals"
+author = DHTech
+author_email = "[email protected]"
+description = "library for working with uncertain, fuzzy, or partially unknown dates and date intervals"
 long_description = file: README.md
-license="Apache License, Version 2.0",
+license="Apache License, Version 2.0"
 long_description_content_type = text/markdown
-url = https://github.com/dh-tech/hackathon-2022
+url = https://github.com/dh-tech/undate-python
 project_urls =
-    Project Home = https://dh-tech.github.io
+    Project Home = https://github.com/dh-tech/undate-python
     Bug Tracker = https://github.com/dh-tech/undate-python/issues
+keywords = "dates dating uncertainty uncertain-dates unknown partially-known digital-humanities"
 classifiers =
     Development Status :: 2 - Pre-Alpha
     Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
     Intended Audience :: Developers
     License :: OSI Approved :: Apache Software License
     Operating System :: OS Independent
     Topic :: Software Development :: Libraries :: Python Modules
     Topic :: Utilities
     Typing :: Typed
 
+# When supported python versions change, update all the following places:
+# - classifiers
+# - minimum version required in python_requires
+# - tox envlist
+# - gh-actions
+# - python versions in matrix config in unit_tests.yml
+
 [options]
 package_dir =
     = src
 packages = find:
 python_requires = >=3.8
 install_requires =
   python-dateutil
+
 [options.extras_require]
 all =
   %(dev)s
@@ -37,13 +49,61 @@ dev =
   black>=22.10.0
   pre-commit>=2.20.0
   tox
-  sphinx
   twine
   wheel
-  pytest-cov
+  build
+  %(docs)s
 test =
   pytest>=7.2
   pytest-ordering
+  pytest-cov
+docs =
+  sphinx
+  sphinx_rtd_theme
+  m2r2
 
 [options.packages.find]
 where = src
+
+[tox:tox]
+envlist = py38, py39, py310, py311
+isolated_build = True
+
+[gh-actions]
+python =
+    3.8: py38
+    3.9: py39
+    3.10: py310
+    3.11: py311
+
+[pytest]
+minversion = 6.0
+addopts = -ra -q
+testpaths =
+    tests
+
+[testenv]
+deps =
+    -e ./[test]
+commands = pytest {posargs}
+
+[testenv:flake8]
+deps =
+    flake8
+commands =
+    flake8 --ignore=E501,E402,F401 src/undate/ tests/
+
+[testenv:coverage]
+deps =
+    -e ./[test]
+commands =
+    pytest --cov=./ --cov-report=xml
+
+[testenv:docs]
+description = invoke sphinx-build to build the HTML docs
+# NOTE: base python should match whatever we're using in GitHub Actions
+basepython = python3.10
+deps =
+    -e ./[docs]
+commands = sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
+           python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'

src/undate/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.0.dev"
+__version__ = "0.1.0"