Convert docs to Sphinx

Author: jwodder

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+formats: all
+python:
+    version: 3
+    install:
+        - requirements: docs/requirements.txt
+        - method: pip
+          path: .
+sphinx:
+    configuration: docs/conf.py
+    fail_on_warning: true

README.rst

@@ -19,6 +19,7 @@
 
 `GitHub <https://github.com/jwodder/pyversion-info>`_
 | `PyPI <https://pypi.org/project/pyversion-info/>`_
+| `Documentation <https://pyversion-info.readthedocs.io>`_
 | `Issues <https://github.com/jwodder/pyversion-info/issues>`_
 | `Changelog <https://github.com/jwodder/pyversion-info/blob/master/CHANGELOG.md>`_
 
@@ -27,7 +28,8 @@
 
 Ever needed to know what Python versions were currently supported, or how many
 subversions a given Python version had?  Wondering how long until a given
-version came out or reached end-of-life?  The answers to these and some other
+version came out or reached end-of-life?  Need to know what CPython versions a
+given PyPy version corresponds to?  The answers to these and some other
 questions can be found with this library.
 
 ``pyversion-info`` pulls its data every run from
@@ -36,6 +38,9 @@ on GitHub.  Prerelease versions are not (currently) included.  I promise
 24-hour turnaround times for keeping the database up-to-date until I am hit by
 a bus.
 
+See `the documentation <https://pyversion-info.readthedocs.io>`_ for more
+information.
+
 
 Installation
 ============
@@ -49,228 +54,48 @@ Installation
 Examples
 ========
 
-Start out by fetching the database:
-
->>> from pyversion_info import get_pyversion_info
->>> pyvinfo = get_pyversion_info()
-
-Get a list of all currently-supported Python series:
-
->>> pyvinfo.supported_series()
-['2.7', '3.5', '3.6', '3.7']
-
-When does 3.8 come out?
-
->>> pyvinfo.release_date("3.8")
-datetime.date(2019, 10, 21)
-
-When does 2.7 reach end-of-life?
-
->>> pyvinfo.eol_date("2.7")
-datetime.date(2020, 1, 1)
-
-Just how many micro versions does 2.7 have, anyway?
-
->>> pyvinfo.subversions("2.7")
-['2.7.0', '2.7.1', '2.7.2', '2.7.3', '2.7.4', '2.7.5', '2.7.6', '2.7.7', '2.7.8', '2.7.9', '2.7.10', '2.7.11', '2.7.12', '2.7.13', '2.7.14', '2.7.15', '2.7.16']
-
-How many versions of Python 3 have been released?
-
->>> pyvinfo.subversions("3")
-['3.0', '3.1', '3.2', '3.3', '3.4', '3.5', '3.6', '3.7']
-
-
-API
-===
-
-Versions are passed to & returned from methods as strings in the form ``"X"``
-(a major version), ``"X.Y"`` (a minor version), or ``"X.Y.Z"`` (a micro
-version).
-
-All dates are returned as ``datetime.date`` objects.
-
-``PyVersionInfo``
------------------
-A class for querying Python versions and their release & EOL dates
-
-``PyVersionInfo(data: dict)``
-   Construct a new ``PyVersionInfo`` object from a `dict` containing version
-   release dates and series EOL dates structured in accordance with `this
-   JSON Schema`__
-
-   __ https://raw.githubusercontent.com/jwodder/pyversion-info-data/master/
-      pyversion-info-data.v1.schema.json
-
-``pyvinfo.eol_date(series: str) -> Optional[date]``
-   Returns the end-of-life date of the given Python version series (i.e., a
-   minor version like 3.5).  The return value may be ``None``, indicating that,
-   though the series is known to the database, its EOL date is not; use
-   ``is_eol()`` to determine whether such a version has reached end-of-life yet
-   or not.
-
-``pyvinfo.is_eol(series: str) -> bool``
-   Returns whether the given version series has reached end-of-life yet
-
-``pyvinfo.is_released(version: str) -> bool``
-   Returns whether the given version has been released yet.  For a major or
-   minor version, this is the whether the first (in version order) micro
-   version has been released.
-
-``pyvinfo.is_supported(version: str) -> bool``
-   Returns whether the given version is currently supported.  For a micro
-   version, this is whether it has been released and the corresponding minor
-   version is not yet end-of-life.  For a major or minor version, this is
-   whether at least one subversion is supported.
-
-``pyvinfo.major_versions() -> List[str]``
-   Returns a list in version order of all known Python major versions (as
-   strings).
-
-``pyinfo.micro_versions() -> List[str]``
-   Returns a list in version order of all Python micro versions.  Versions in
-   the form ``X.Y`` are included here as ``X.Y.0``.
-
-``pyvinfo.minor_versions() -> List[str]``
-   Returns a list in version order of all Python minor versions.
-
-``pyvinfo.release_date(version: str) -> Optional[date]``
-   Returns the release date of the given Python version.  For a major or minor
-   version, this is the release date of its first (in version order) micro
-   version.  The return value may be ``None``, indicating that, though the
-   version is known to the database, its release date is not; use
-   ``is_released()`` to determine whether such a version has been released or
-   not.
+(The given outputs are current as of 2021-11-04.)
 
-``pyvinfo.subversions(version: str) -> List[str]``
-   Returns a list in version order of all subversions of the given version.  If
-   ``version`` is a major version, this is all of its released minor versions.
-   If ``version`` is a minor version, this is all of its released micro
-   versions.
-
-``pyvinfo.supported_series() -> List[str]``
-   Returns a list in version order of all Python version series (i.e., minor
-   versions like 3.5) that are currently supported (i.e., that have at least
-   one release made and are not yet end-of-life)
-
-
-Utilities
----------
-
-``UnknownVersionError``
-   Subclass of ``ValueError`` raised when ``PyVersionInfo`` is asked for
-   information about a version that does not appear in its database.
-   Operations that result in an ``UnknownVersionError`` may succeed later as
-   more Python versions are announced & released.
-
-   The unknown version is stored in an ``UnknownVersionError`` instance's
-   ``version`` attribute.
-
-``get_pyversion_info(url: str = pyversion_info.DATA_URL, cache_dir: Optional[str] = pyversion_info.CACHE_DIR) -> PyVersionInfo``
-    Fetches the latest version release data from ``url`` and returns a new
-    ``PyVersionInfo`` object.  The HTTP response is cached in ``cache_dir`` to
-    speed up future requests (or ``cache_dir`` can be set to ``None`` to
-    disable caching).
-
-
-Command
-=======
-
-*New in version 0.4.0*
-
-``pyversion-info`` also provides a command of the same name for querying
-information about Python versions from the command line::
-
-    pyversion-info [<global-options>] <command> [<args> ...]
-
-Currently, ``pyversion-info`` has two subcommands, ``list`` and ``show``.
-
-
-Global Options
---------------
-
--d DATABASE, --database DATABASE
-                                Use the given JSON file as the version
-                                information database instead of fetching data
-                                from the default URL.  ``DATABASE`` can be
-                                either an HTTP or HTTPS URL or a path to a
-                                local file.
-
-
-``pyversion-info list``
------------------------
-
-::
-
-    pyversion-info [<global-options>] list [<options>] {major|minor|micro}
-
-List all major, minor, or micro Python versions, one per line.
-
-
-Options
-^^^^^^^
-
--a, --all                       List all known versions of the given level
--n, --not-eol                   Only list versions that have not yet reached
-                                end-of-life (i.e., all supported versions plus
-                                all unreleased versions)
--r, --released                  Only list released versions.  This is the
-                                default.
--s, --supported                 Only list currently-supported versions
-
-
-``pyversion-info show``
------------------------
+Start out by fetching the database:
 
-::
+>>> from pyversion_info import VersionDatabase
+>>> vd = VersionDatabase.fetch()
 
-    pyversion-info [<global-options>] show [<options>] <version>
+Get a list of all currently-supported CPython series:
 
-Show various information about a given Python version.
+>>> vd.cpython.supported_series()
+['3.6', '3.7', '3.8', '3.9', '3.10']
 
-For a major version, the output is of the form::
+When does 3.11 come out?
 
-    Version: 3
-    Level: major
-    Release-date: 2008-12-03
-    Is-released: yes
-    Is-supported: yes
-    Subversions: 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9
+>>> vd.cpython.release_date("3.11")
+datetime.date(2022, 10, 3)
 
-For a minor version, the output is of the form::
+When does 3.6 reach end-of-life?
 
-    Version: 3.3
-    Level: minor
-    Release-date: 2012-09-29
-    Is-released: yes
-    Is-supported: no
-    EOL-date: 2017-09-29
-    Is-EOL: yes
-    Subversions: 3.3.0, 3.3.1, 3.3.2, 3.3.3, 3.3.4, 3.3.5, 3.3.6, 3.3.7
+>>> vd.cpython.eol_date("3.6")
+datetime.date(2021, 12, 23)
 
-For a micro version, the output is of the form::
+Just how many micro versions does 3.9 have, anyway?
 
-    Version: 3.9.5
-    Level: micro
-    Release-date: 2021-05-03
-    Is-released: yes
-    Is-supported: yes
+>>> vd.cpython.subversions("3.9")
+['3.9.0', '3.9.1', '3.9.2', '3.9.3', '3.9.4', '3.9.5', '3.9.6', '3.9.7', '3.9.8', '3.9.9', '3.9.10', '3.9.11']
 
+What major versions of PyPy are there?
 
-Options
-^^^^^^^
+>>> vd.pypy.major_versions()
+['1', '2', '4', '5', '6', '7']
 
--J, --json                      Output JSON
+What CPython series do PyPy 7.3.\* support?
 
--S, --subversions <all|not-eol|released|supported>
-                                Which subversions to list; the choices have the
-                                same meanings as the ``list`` options of the
-                                same name  [default: released]
+>>> vd.pypy.supports_cpython_series("7.3")
+['2.7', '3.6', '3.7', '3.8']
 
 
 Caveats
 =======
 
-The database is generally only updated when an edit is made to a release
-schedule PEP.  Occasionally, a deadline listed in a PEP is missed, but the PEP
-is not updated for a couple days, and so for a brief period this library will
-falsely report the given version as released.
+The CPython database is generally only updated when an edit is made to a
+release schedule PEP.  Occasionally, a deadline listed in a PEP is missed, but
+the PEP is not updated for a couple days, and so for a brief period this
+library will falsely report the given version as released.

docs/api.rst

@@ -0,0 +1,33 @@
+.. currentmodule:: pyversion_info
+
+API
+===
+
+Versions are passed to & returned from methods as strings in the form ``"X"``
+(a major version), ``"X.Y"`` (a minor version), or ``"X.Y.Z"`` (a micro
+version).
+
+All dates are returned as `datetime.date` objects.
+
+.. autoclass:: VersionDatabase()
+    :exclude-members: fetch
+
+    .. automethod:: fetch(url: str = DATA_URL, cache_dir: Union[str, pathlib.Path, None] = CACHE_DIR) -> pyversion_info.VersionDatabase
+        :noindex:
+
+.. autoclass:: VersionInfo()
+
+.. autoclass:: CPythonVersionInfo()
+    :show-inheritance:
+
+.. autoclass:: PyPyVersionInfo()
+    :show-inheritance:
+
+.. autoexception:: UnknownVersionError
+    :show-inheritance:
+
+.. autodata:: DATA_URL
+    :annotation:
+
+.. autodata:: CACHE_DIR
+    :annotation:

docs/changelog.rst

@@ -0,0 +1,64 @@
+.. currentmodule:: pyversion_info
+
+Changelog
+=========
+
+v1.0.0 (in development)
+-----------------------
+- Support Python 3.10
+- Drop support for Python 3.6
+- Support for fetching information on PyPy versions has been added.  With it
+  come the following changes:
+
+  - The schema used by the database (and thus the URL for the default database)
+    has been modified
+  - ``PyVersionInfo`` has been renamed to `CPythonVersionInfo`
+  - A new `PyPyVersionInfo` class has been added
+  - A new `VersionDatabase` class has been added, containing a
+    `CPythonVersionInfo` instance and a `PyPyVersionInfo` instance
+  - ``get_pyversion_info()`` is now `VersionDatabase.fetch()`
+  - The command-line interface now takes a ``--pypy`` option for showing
+    details about PyPy versions
+
+- The ``unreleased`` argument to `~VersionInfo.major_versions()`,
+  `~VersionInfo.minor_versions()`, `~VersionInfo.micro_versions()`, and
+  `~VersionInfo.subversions()` has been removed; the methods now return all
+  known versions, released & unreleased
+- `~VersionInfo.release_date()` now returns `None` for any known version whose
+  release date is unknown, whether it's been released yet or not.  Use
+  `~VersionInfo.is_released()` to determine whether such a version has been
+  released.
+- `~CPythonVersionInfo.eol_date()` now returns `None` for any known version
+  whose EOL date is unknown, whether it's EOL yet or not.  Use
+  `~CPythonVersionInfo.is_eol()` to determine whether such a version has
+  reached end-of-life.
+
+
+v0.4.0 (2021-10-03)
+-------------------
+- `~VersionInfo.major_versions()`, `~VersionInfo.minor_versions()`,
+  `~VersionInfo.micro_versions()`, and `~VersionInfo.subversions()` now take
+  optional ``unreleased`` arguments for including unreleased versions
+- `~CPythonVersionInfo.is_supported()` now accepts major and micro versions
+- `UnknownVersionError` now inherits `ValueError`
+- Added a command-line interface
+
+
+v0.3.0 (2021-10-01)
+-------------------
+- Add type annotations
+- Switch from appdirs to platformdirs
+
+
+v0.2.0 (2020-12-13)
+-------------------
+- Support Python 3.8 and 3.9
+- Add a note to the README about the possibility of release deadlines being
+  missed
+- Drop support for Python 2.7, 3.4, and 3.5
+- Properly close the ``requests`` session after downloading the database
+
+
+v0.1.0 (2019-04-23)
+-------------------
+Initial release