write docs

.github/workflows/test.yml

@@ -26,3 +26,24 @@ jobs:
     - name: Test with tox
       run: |
         tox -e py
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r doc/doc-requirements.txt
+      - name: Build documentation
+        run: |
+          python -m sphinx -W -an doc build
+      - uses: actions/upload-artifact@v3
+        with:
+          name: sphinx-out
+          path: ./build/
+          retention-days: 5

.readthedocs.yml

@@ -0,0 +1,26 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+  - epub
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: doc/doc-requirements.txt

README.md

@@ -2,6 +2,9 @@
 
 [![PyPI - Version](https://img.shields.io/pypi/v/win-precise-time.svg)](https://pypi.org/project/win-precise-time)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/win-precise-time.svg)](https://pypi.org/project/win-precise-time)
+[![Documentation Status](https://readthedocs.org/projects/win-precise-time/badge/?version=latest)](https://win-precise-time.readthedocs.io/en/latest/?badge=latest)
+
+The documentation is available [here](https://win-precise-time.readthedocs.io/en/latest/).
 
 -----
 
@@ -34,10 +37,10 @@ pip install win-precise-time
 ## Usage
 
 ```python-repl
->>> import win_precise_time
->>> win_precise_time.time()  # retrieve current time
+>>> import win_precise_time as wpt
+>>> wpt.time()  # retrieve current time
 1654539449.4548845
->>> win_precise_time.sleep(0.001)  # sleep for 1ms
+>>> wpt.sleep(0.001)  # sleep for 1ms
 ```
 
 ## Test

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/api.rst

@@ -0,0 +1,71 @@
+Library API
+-----------
+
+.. _timestamp functions:
+
+Timestamp Functions
+^^^^^^^^^^^^^^^^^^^
+
+.. function:: win_precise_time.time() -> float
+
+   Return the time in seconds since the `epoch`_ as a floating point number.
+   See :func:`time.time` for a detailed description. This function provides
+   a timestamp with <1us resolution while the builtin :func:`~time.time` function
+   has a resolution of around 15ms.
+
+   :return:
+      timestamp in seconds
+
+
+.. function:: win_precise_time.time_ns() -> int
+
+   Similar to :func:`time` but returns time as an integer number of nanoseconds
+   since the `epoch`_.
+
+   :return:
+      timestamp in nanoseconds
+
+.. _sleep functions:
+
+Sleep Functions
+^^^^^^^^^^^^^^^
+
+.. function:: win_precise_time.sleep(secs: float, /) -> None
+
+   Suspend execution of the calling thread for the given number of seconds.
+   See :func:`time.sleep` for a detailed description. This function provides
+   the same accuracy as the Python 3.11 implementation.
+   Earlier Python version were unable to achieve sub-millisecond precision.
+
+   :param float secs:
+      the sleep duration in seconds
+
+.. function:: win_precise_time.sleep_until(t_wakeup_s: float, /) -> None
+
+   Suspend execution of the calling thread until :func:`time` == *t_wakeup_s*.
+
+   :param float t_wakeup_s:
+      the wakeup time in seconds since the `epoch`_
+
+.. function:: win_precise_time.sleep_until_ns(t_wakeup_ns: int, /) -> None
+
+   Suspend execution of the calling thread until :func:`time_ns` == *t_wakeup_ns*.
+
+   :param int t_wakeup_ns:
+      the wakeup times in nanoseconds since the `epoch`_
+
+.. function:: win_precise_time.hotloop_until_ns(t_wakeup_ns: int, /) -> None
+
+   Run a busy loop until :func:`time_ns` == *t_wakeup_ns*.
+   This function fully loads the CPU core and does not release the
+   global interpreter lock (GIL). This function must only be used for
+   very short wait time to achieve the highest wakeup time precision.
+
+   :param int t_wakeup_ns:
+      the wakeup time in nanoseconds since the `epoch`_
+
+   .. warning::
+      :func:`hotloop_until_ns` makes the process unresponsive.
+      It is only useful for very short high precision waiting.
+
+.. _epoch: https://docs.python.org/3/library/time.html#epoch

doc/conf.py

@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Imports -----------------------------------------------------------------
+import re
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "win-precise-time"
+copyright = "2022, Artur Drogunow"
+author = "Artur Drogunow"
+
+with open("../src/win_precise_time/__init__.py", "r", encoding="utf-8") as f:
+    __version__ = re.search(
+        r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE
+    ).group(1)
+
+version = __version__.split("-", maxsplit=1)[0]
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = []

doc/doc-requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=5.2.3
+furo

doc/examples.rst

@@ -0,0 +1,64 @@
+Examples
+========
+
+.. _timestamp resolution example:
+
+Timestamp Resolution Example
+----------------------------
+
+.. literalinclude:: ../examples/timestamp_resolution.py
+   :language: python
+   :linenos:
+
+Output::
+
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756698370
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756715059
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756718636
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756721973
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756725311
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756728649
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756731749
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756735563
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756738901
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756742001
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756745338
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756748676
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756752014
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756755829
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756758928
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756762028
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756765366
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756768465
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756771326
+   time.time()=1665189245.756171703 - wpt.time()=1665189245.756774426
+
+:func:`win_precise_time.time` always provides a fresh timestamp while the builtin
+:func:`time.time` is updated every 15ms.
+
+Soft Realtime Example
+---------------------
+
+.. literalinclude:: ../examples/soft_realtime.py
+   :language: python
+   :linenos:
+
+Output::
+
+   0.00101 - 1ms task
+   0.00200 - 1ms task
+   0.00301 - 1ms task
+   0.00400 - 1ms task
+   0.00504 - 1ms task
+   0.00508 - 5ms task
+   0.00600 - 1ms task
+   0.00705 - 1ms task
+   0.00806 - 1ms task
+   0.00902 - 1ms task
+   0.01000 - 1ms task
+   0.01004 - 5ms task
+   0.01005 - 10ms task
+
+.. note::
+   In larger applications the garbage collector (:mod:`gc`) will become problematic for timing precision.
+   Use :func:`gc.disable` if your application allows it.

doc/index.rst

@@ -0,0 +1,84 @@
+win-precise-time
+================
+
+.. only:: html
+
+   .. image:: https://img.shields.io/pypi/v/win-precise-time.svg
+       :target: https://pypi.org/project/win-precise-time
+       :alt: PyPI - Version
+   .. image:: https://img.shields.io/pypi/pyversions/win-precise-time.svg
+       :target: https://pypi.org/project/win-precise-time
+       :alt: PyPI - Python Version
+   .. image:: https://readthedocs.org/projects/win-precise-time/badge/?version=latest
+       :target: https://win-precise-time.readthedocs.io/en/latest/?badge=latest
+       :alt: Documentation Status
+   .. image:: https://github.com/zariiii9003/win-precise-time/actions/workflows/test.yml/badge.svg
+       :target: https://github.com/zariiii9003/win-precise-time/actions
+       :alt: Github Actions
+
+.. toctree::
+   :maxdepth: 2
+
+   self
+   api
+   examples
+
+Description
+-----------
+
+This Windows-only library provides a few improvements over the builtin :mod:`time` functions.
+
+The :ref:`timestamp functions` of ``win-precise-time`` achieve a much better resolution than the builtin function
+by using `GetSystemTimePreciseAsFileTime`_. On Windows the builtin :func:`time.time` function has a resolution of 15ms
+while :func:`win_precise_time.time` has nanosecond resolution as seen in the :ref:`timestamp resolution example`.
+
+The :ref:`sleep functions` use `high resolution timers`_ to enable sleep with sub-milliseconds precision. This change
+was also implemented in `CPython 3.11 <https://github.com/python/cpython/pull/29203>`_. High resolution timers
+are supported in Windows 10 version 1803 and later. Older Windows versions will not see any sleep precision improvement
+with this library.
+
+All functions of this library are implemented in C.
+
+Installation
+------------
+You can install ``win-precise-time`` from `PyPI`_::
+
+   python -m pip install win-precise-time
+
+Usage
+-----
+
+>>> import win_precise_time as wpt
+>>> wpt.time()  # retrieve current time
+1654539449.4548845
+>>> wpt.sleep(0.001)  # sleep for 1ms
+
+
+Test
+----
+
+Run the tests with::
+
+   python -m pip install tox
+   tox
+
+
+Build
+-----
+
+Build ``win-precise-time`` with::
+
+   python -m pip install build
+   python -m build .
+
+
+License
+-------
+
+``win-precise-time`` is distributed under the terms of the `MIT`_ license.
+
+
+.. _GetSystemTimePreciseAsFileTime: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime
+.. _high resolution timers: https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-createwaitabletimerexw
+.. _PyPI: https://pypi.org/project/win-precise-time/
+.. _MIT: https://spdx.org/licenses/MIT.html