docs: add documentation

Author: dlech

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .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.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/api/index.rst

@@ -0,0 +1,10 @@
+=============
+API reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   winsdk
+   windows

docs/api/windows.rst

@@ -0,0 +1,27 @@
+===============================
+:mod:`winsdk.windows` namespace
+===============================
+
+The :mod:`winsdk.windows` package contains the automatically generate bindings
+for the Windows SDK.
+
+Since most of the code is generated, there currently aren't Python API docs.
+You can use https://learn.microsoft.com/en-us/uwp/api/ instead, keeping in mind
+the Python naming conventions and other rules mentioned in :doc:`../types` section.
+
+.. tip:: The ``winsdk`` package includes type hints so you can use those if
+    you are unsure of a return type or a parameter type.
+
+.. todo:: We could consider using https://github.com/MicrosoftDocs/winrt-api to autogenerate Python docs.
+
+---------------
+Interop modules
+---------------
+
+There are also special ``interop`` modules that provide extra functionality
+to bridge between WinRT and other interfaces.
+
+.. toctree::
+   :maxdepth: 2
+
+   windows/graphics.capture.interop

docs/api/windows/graphics.capture.interop.rst

@@ -0,0 +1,30 @@
+=====================================================
+:mod:`winsdk.windows.graphics.capture.interop` module
+=====================================================
+
+APIs for desktop interop with the `Windows.Graphics.Capture
+<https://learn.microsoft.com/uwp/api/windows.graphics.capture>`_ namespace.
+
+
+.. function:: create_for_monitor(monitor)
+
+    Targets a monitor(s) for the creation of a graphics capture item.
+
+    :param int monitor: The monitor handle (``HMONITOR``) that represents the monitor to capture.
+
+    :return: A graphics capture item.
+    :rtype: :obj:`winsdk.windows.graphics.capture.GraphicsCaptureItem`
+
+    .. seealso:: https://learn.microsoft.com/windows/win32/api/windows.graphics.capture.interop/nf-windows-graphics-capture-interop-igraphicscaptureiteminterop-createformonitor
+
+
+.. function:: create_for_window(window)
+
+    Targets a single window for the creation of a graphics capture item.
+
+    :param int window: The window handle (``HWND``) that represents the window to capture.
+
+    :return: A graphics capture item.
+    :rtype: :obj:`winsdk.windows.graphics.capture.GraphicsCaptureItem`
+
+    .. seealso:: https://learn.microsoft.com/windows/win32/api/windows.graphics.capture.interop/nf-windows-graphics-capture-interop-igraphicscaptureiteminterop-createforwindow

docs/api/winsdk.rst

@@ -0,0 +1,55 @@
+===========================
+:mod:`winsdk.system` module
+===========================
+
+.. class:: Object
+
+    A wrapper around the WinRT ``System.Object`` type. 
+    
+    This is the base type of all WinRT runtime objects and cannot be
+    instantiated directly.
+
+    This type currently has no members.
+
+.. class:: Array(type, [initializer, ] /)
+
+    A wrapper around the WinRT ``System.Array`` type.
+
+    This type implements the Python sequence protocol.
+
+    :param type:
+        The type to use for elements of the array. This can be a WinRT
+        type or a format string for fundamental types.
+    :type type: str or type
+    :param initializer:
+        An optional iterator of values to use to initialize the array.
+        If an integer value is given, an empty array of that size will
+        be initialized. For value types, any object supporting the
+        CPython buffer protocol with the correct layout can be used
+        as an initializer.
+    :type initializer: int or iter or buffer
+
+
+    Creation examples::
+
+        from winsdk import Array
+        from winsdk.windows.foundation import Point
+
+        # array of 10 32-bit unsigned integers.
+        a1 = Array("I", 10)
+        # array of 3 points with initial values
+        a2 = Array(Point, [Point(1, 1), Point(2, 2), Point(3, 3)])
+
+    Sequence protocol examples::
+
+        # get the number of elements in the array
+        size = len(a1)
+        # get the first element of the array
+        item = a1[0]
+        # get the last element of the array
+        item = a1[-1]
+        # iterate all items of the array
+        for item in a1: ...
+        # test for element in array
+        if item in a1: ...
+

docs/conf.py

@@ -0,0 +1,39 @@
+# 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 = 'winsdk'
+copyright = '2022-2023, David Lechner'
+author = 'David Lechner'
+
+# -- General configuration --
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+]
+
+# templates_path = ['_templates']
+exclude_patterns = ['.venv', '_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 = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Options for intersphinx extension --
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+# -- Options for todo extension --
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
+todo_include_todos = True

docs/index.rst

@@ -0,0 +1,22 @@
+======
+winsdk
+======
+
+The ``winsdk`` package provides access to Windows Runtime (WinRT) APIs.
+
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   types
+   api/index
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% -W %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==6.1.3
+sphinx-rtd-theme==1.2.0