From 4f561f331edd8f27c9fce699bb02f412904c25ea Mon Sep 17 00:00:00 2001 From: blep Date: Mon, 28 Aug 2023 14:12:06 +0200 Subject: [PATCH] Fixed readme typos. Started working on doc generation with Sphinx. --- README.md | 2 +- docs/Makefile | 20 +++++++++++ docs/conf.py | 32 ++++++++++++++++++ docs/index.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 8 +++-- 5 files changed, 151 insertions(+), 3 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/README.md b/README.md index d6d66f6..c30bef3 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Columns content: - short process path - window title -Action made to produce this event: +Actions made to produce this event: - Bring Firefox window to focus by click on it in the Taskbar. Events with `explorer.exe` are interactions with the Taskbar. - Bring Notion app to focus by click on it in the Taskbar. - Bring back cmd.exe to focus by click on it in the Taskbar. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..955d200 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,32 @@ +import sphinx_rtd_theme + +# 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 + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'win32-window-monitor' +copyright = '2023, Baptiste Lepilleur' +author = 'Baptiste Lepilleur' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "myst_parser", +] + +templates_path = ['_templates'] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b22e46b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,92 @@ +.. win32-window-monitor documentation master file, created by + sphinx-quickstart on Sun Aug 27 11:12:24 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +win32-window-monitor +==================== + +Monitor change of the focused window on Windows Operating System: + +- Reports the focused window HWND, pid and executable path to a python callback + registered using `SetWinEventHook `_. + +- Provides helpers function to easily retrieve process id and path from the + callback parameters. + +Example +======= + +The main.py shows how to use the API to produce the example output below. After +installing the ``win32-window-monitor`` package, the script ``log_focused_window`` +is installed. + +.. code-block:: batch + + pip install win32-window-monitor + log_focused_window + +which produces the following output: + +.. code-block:: text + + 101307546:0.00 Capture W:0x1014c P:7440 T:7592 Windows\explorer.exe Running applications + 101307687:0.14 Foreground W:0x903ce P:2508 T:1988 net\firefox.exe blep/win32_window_monitor: Monitor change of the focused window on Windows O.S.. Reports the focused window HWND, pid and executable to a Python callback. — Mozilla Firefox + 101307687:0.00 Focus W:0x903ce P:2508 T:1988 net\firefox.exe blep/win32_window_monitor: Monitor change of the focused window on Windows O.S.. Reports the focused window HWND, pid and executable to a Python callback. — Mozilla Firefox + 101312015:4.33 Show W:0xc080c P:7440 T:7592 Windows\explorer.exe + 101312015:0.00 Show W:0x10150 P:7440 T:7592 Windows\explorer.exe + 101312031:0.02 Show W:0x1065e P:12428 T:11660 Notion\Notion.exe Chrome Legacy Window + 101312312:0.28 Capture W:0x1014c P:7440 T:7592 Windows\explorer.exe Running applications + 101312468:0.16 Foreground W:0x20642 P:12428 T:11660 Notion\Notion.exe Python: automated CI/Release/doc/Wheel + 101312484:0.02 Focus W:0x20642 P:12428 T:11660 Notion\Notion.exe Python: automated CI/Release/doc/Wheel + 101312484:0.00 Show W:0x20642 P:12428 T:11660 Notion\Notion.exe Python: automated CI/Release/doc/Wheel + 101314312:1.83 Capture W:0x1014c P:7440 T:7592 Windows\explorer.exe Running applications + 101314421:0.11 Foreground W:0x440820 P:16088 T:7192 System32\conhost.exe C:\Windows\System32\cmd.exe - python -m win32_window_monitor.main + 101314437:0.02 Focus W:0x440820 P:16088 T:7192 System32\conhost.exe C:\Windows\System32\cmd.exe - python -m win32_window_monitor.main + +Columns content: + +- event time_ms : elapsed second since last event +- event +- W: HWND, the window handle +- P: process id +- T: thread id +- short process path +- window title + +Actions made to produce this event: +- Bring Firefox window to focus by click on it in the Taskbar. Events with `explorer.exe` are interactions with the Taskbar. +- Bring Notion app to focus by click on it in the Taskbar. +- Bring back cmd.exe to focus by click on it in the Taskbar. + +Usage example +============= + +IMPORTANT: you need more than just SYSTEM_FOREGROUND to capture all +events that bring a window to the foreground. SYSTEM_FOREGROUND for +example is not generated when restoring a minimized window. + +.. literalinclude:: ../win32_window_monitor/main_usage_example.py + + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +.. automodule:: win32_window_monitor + :members: + +.. autosummary:: + :toctree: generated + + +.. include ../README.md + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/pyproject.toml b/pyproject.toml index 0237186..8d3f8b5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,9 +37,13 @@ log_focused_window = "win32_window_monitor:main" [project.optional-dependencies] test = [ "pytest ~= 7.3.2", - "coverage ~= 7.3.0" + "coverage ~= 7.3.0", +] +doc = [ + "sphinx ~= 7.2.3", + "sphinx-rtd-theme ~= 1.3.0", + "myst-parser ~= 2.0.0", ] -doc = ["sphinx ~= 7.2.3"] #[tool.poetry.dev-dependencies] ## Release